okmain 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b1c82cf5cfc87c588329a84ccb9b8118f7f27d7818a45150b021310dc28e2049
-  data.tar.gz: bef38f1590b89386ec4c8c9287edb55b5bb08255c787ec7b75d3ac45a6a81580
+  metadata.gz: 56e572b6cb9c8626fa17484a93fb4b5172d4f34f653071b7ca223548dd067926
+  data.tar.gz: 200af9151a6a0efd3abb01374eba1899b952c4e3b61a6455cd651fdf97516ecc
 SHA512:
-  metadata.gz: dba390c347ccd57cd71ee46b03ae5699614c6754802e8c465cf700025d078eeca8982374a575705f810469801190310e14c11c379df2808b6cce6a8eff13e0d3
-  data.tar.gz: b740152ded762d8bea52e83d81ee6eab78aab7ccc3a41ecbdf1be6e253051315dbd3f92fe553dc8df609adf0dcf7027ad7842c97cc54d7993dcbf7161b72d33e
+  metadata.gz: 88803b1165696b26217ca5ed76f15b0f1e946e8280b73a084c62d7f37878ffef5465ceadb071f14a1c6fedf0e3d8699a1f3942f841f5c560a92b87b8c76e9f87
+  data.tar.gz: 11b17ecaef7d6cd283e6042674f07ab3a40e06ac8a15c1d1c80f147f31ba9da627f15757cdb80ab8ccc24c85da2fccc3281a297f83e6805317505f359a7bec57

data/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project might adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.html) if I ever get around to releasing a 1.0, but I wouldn't count on that happening any time soon.
+
+## [Unreleased]
+
+- May try to make KMeans faster: now that I have harvested the low-hanging fruit in sampler performance, kmeans is almost 90% of runtime on my test images.
+- Adding a suite of test images and automating benchmarking new versions against old versions for speed and correctness would be cool.
+- Even starting this project was AI psychosis. Would have been smarter to see if I like the output of the algorithm for the one specific thing I need this for first, no?
+
+## [0.2.1] - 2026-04-25
+
+### Added
+- `Okmain::Oklab` conversion helpers needed by a downstream app:
+  `srgb_to_linear`, `srgb8_to_oklab`, `oklab_to_oklch`, `oklch_to_oklab`,
+  `srgb8_to_oklch`. Hue is in degrees, normalized to `[0, 360)`.
+
+## [0.2.0] - 2026-04-25
+
+### Changed
+- RNG replaced with a Xoshiro256++ implementation matching the upstream Rust
+  `okmain` crate, so results closely track the reference implementation.
+  Output for a given image will differ from 0.1.0.
+- Sampler, distance mask, scorer, and Oklab conversion paths reworked for
+  speed and closer parity with the Rust implementation.
+
+### Added
+- `Okmain::Xoshiro` PRNG (`lib/okmain/xoshiro.rb`).
+- `bench.rb` benchmark script and a `rust_compare/` companion crate for
+  apples-to-apples timing and output comparisons against the Rust crate.
+- `Rakefile` exposing the standard `bundler/gem_tasks` (`build`, `install`,
+  `release`).
+- Development dependencies: `benchmark ~> 0.4`, `rake ~> 13.0`.
+
+## [0.1.0] - 2026-04-24
+
+### Added
+- Initial port of the Rust `okmain` crate to Ruby: extracts up to 4 dominant
+  colors from an image via adaptive K-means clustering in Oklab space.
+- `ruby-vips`-based image loading with block-average downsampling.
+- Dual MIT / Apache-2.0 licensing matching the upstream crate.
+- README with install and usage examples.
+
+[Unreleased]: https://github.com/midnightmonster/okmain-ruby/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/midnightmonster/okmain-ruby/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/midnightmonster/okmain-ruby/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/midnightmonster/okmain-ruby/releases/tag/v0.1.0

data/README.md

@@ -62,6 +62,35 @@ Colors are returned as `[r, g, b]` arrays (0-255), sorted by score descending. T
 3. **Score** — Centroids ranked by a weighted combination of pixel count (with center-priority mask) and chroma
 4. **Return** — Up to 4 `[r, g, b]` arrays sorted by score
 
+## Comparing with the Rust implementation
+
+A small Rust binary is included in `rust_compare/` for verifying results against the original [okmain](https://github.com/si14/okmain) crate. Requires [Rust](https://rustup.rs/) 1.93+.
+
+Build it once:
+
+```
+cd rust_compare
+cargo build --release
+```
+
+Then compare outputs on any image:
+
+```bash
+# Rust
+rust_compare/target/release/rust_compare path/to/photo.jpg
+
+# Ruby
+bundle exec ruby -e "require 'okmain'; pp Okmain.colors('path/to/photo.jpg')"
+```
+
+Both print `[r, g, b]` arrays in the same order, so results can be diffed directly.
+
+For benchmarking (against rust, but mostly to catch progress or regression in the gem), use:
+
+```bash
+bundle exec ruby bench.rb path/to/image.png
+```
+
 ## Credits
 
 Based on the Rust [okmain](https://github.com/si14/okmain) crate (v0.2.0) by Dan Groshev and okmain contributors.

data/lib/okmain/config.rb

@@ -2,14 +2,24 @@
 
 module Okmain
   class Config
-    attr_reader :chroma_weight, :mask_weighted_counts_weight
+    attr_reader :chroma_weight, :mask_weighted_counts_weight,
+                :mask_weight, :mask_saturated_threshold
 
-    def initialize(chroma_weight: 0.7, mask_weighted_counts_weight: 0.3)
+    def initialize(
+      chroma_weight: 0.7,
+      mask_weighted_counts_weight: 0.3,
+      mask_weight: 1.0,
+      mask_saturated_threshold: 0.3
+    )
       raise ArgumentError, "chroma_weight must be between 0 and 1" unless (0.0..1.0).cover?(chroma_weight)
       raise ArgumentError, "mask_weighted_counts_weight must be between 0 and 1" unless (0.0..1.0).cover?(mask_weighted_counts_weight)
+      raise ArgumentError, "mask_weight must be between 0 and 1" unless (0.0..1.0).cover?(mask_weight)
+      raise ArgumentError, "mask_saturated_threshold must be between 0 and 0.5 (exclusive)" unless mask_saturated_threshold >= 0.0 && mask_saturated_threshold < 0.5
 
       @chroma_weight = chroma_weight.to_f
       @mask_weighted_counts_weight = mask_weighted_counts_weight.to_f
+      @mask_weight = mask_weight.to_f
+      @mask_saturated_threshold = mask_saturated_threshold.to_f
     end
   end
 end

data/lib/okmain/distance_mask.rb

@@ -2,23 +2,24 @@
 
 module Okmain
   module DistanceMask
-    SATURATED_THRESHOLD = 0.75
-
     module_function
 
-    # Returns a flat Array of mask values (0.1..1.0) for each pixel, matching Rust's rectangular mask.
+    # Returns a flat Array of mask values (0.1..1.0) for each pixel,
+    # matching the Rust rectangular mask exactly.
     # Center pixels get 1.0, corner pixels get 0.1, with a linear ramp.
-    def compute(width, height)
-      half_w = width * 0.5
-      half_h = height * 0.5
-      x_threshold = half_w * SATURATED_THRESHOLD
-      y_threshold = half_h * SATURATED_THRESHOLD
+    def compute(width, height, saturated_threshold)
+      w = width.to_f
+      h = height.to_f
+      middle_x = w / 2.0
+      middle_y = h / 2.0
+      x_threshold = w * saturated_threshold
+      y_threshold = h * saturated_threshold
 
       mask = Array.new(width * height)
       y = 0
       while y < height
-        # Distance from nearest y-edge (0 at edge, half_h at center)
-        my = y < half_h ? y.to_f : (height - 1 - y).to_f
+        yf = y.to_f
+        my = yf <= middle_y ? yf : h - yf
         y_contrib = if y_threshold > 0.0
                       v = 0.1 + 0.9 * (my / y_threshold)
                       v < 1.0 ? v : 1.0
@@ -29,8 +30,8 @@ module Okmain
         row_offset = y * width
         x = 0
         while x < width
-          # Distance from nearest x-edge (0 at edge, half_w at center)
-          mx = x < half_w ? x.to_f : (width - 1 - x).to_f
+          xf = x.to_f
+          mx = xf <= middle_x ? xf : w - xf
           x_contrib = if x_threshold > 0.0
                         v = 0.1 + 0.9 * (mx / x_threshold)
                         v < 1.0 ? v : 1.0

data/lib/okmain/kmeans.rb

@@ -7,13 +7,14 @@ module Okmain
     LLOYDS_CONVERGENCE_TOL = 1e-3
     SIMILAR_CLUSTER_DISTANCE_SQ = 0.005
     KMEANSPP_CANDIDATES = 3
+    RANDOM_SEED = 314159
 
     module_function
 
     # Returns [centroids, assignments] where centroids is Array of [L, a, b]
     # and assignments is Array of centroid indices per pixel.
     def cluster(pixels, k: MAX_CENTROIDS)
-      rng = Random.new(42)
+      rng = Xoshiro256PlusPlus.new(RANDOM_SEED)
       n = pixels.size
       return [pixels.dup, Array.new(n) { |i| i }] if n <= k
 
@@ -45,7 +46,7 @@ module Okmain
     # K-means++ initialization with 3 candidates per step
     def init_plusplus(pixels, k, rng)
       n = pixels.size
-      centroids = [pixels[rng.rand(n)].dup]
+      centroids = [pixels[rng.random_range(n)].dup]
 
       dist_sq = Array.new(n, Float::INFINITY)
 
@@ -64,13 +65,13 @@ module Okmain
         best_potential = Float::INFINITY
 
         KMEANSPP_CANDIDATES.times do
-          # Weighted random selection
-          r = rng.rand * total
+          # Weighted random selection (matching Rust's sample_by_distance)
+          r = rng.random_f32 * total
           cumulative = 0.0
           idx = 0
           while idx < n
             cumulative += dist_sq[idx]
-            if cumulative >= r
+            if cumulative > r
               break
             end
             idx += 1
@@ -143,7 +144,7 @@ module Okmain
         while c < k
           if counts[c] == 0
             # Reassign empty cluster to random data point
-            ri = rng.rand(n)
+            ri = rng.random_range(n)
             new_centroids[c] = pixels[ri].dup
           else
             inv = 1.0 / counts[c]

data/lib/okmain/oklab.rb

@@ -38,16 +38,6 @@ module Okmain
       [r, g, b_]
     end
 
-    # sRGB component (0..255) → linear (0..1)
-    def srgb_to_linear(c)
-      c = c / 255.0
-      if c <= 0.04045
-        c / 12.92
-      else
-        ((c + 0.055) / 1.055)**2.4
-      end
-    end
-
     # Linear (0..1) → sRGB component (0..255), clamped
     def linear_to_srgb(c)
       c = c.clamp(0.0, 1.0)
@@ -59,10 +49,45 @@ module Okmain
       (c * 255.0).round.clamp(0, 255)
     end
 
+    # sRGB component (0..255) → linear (0..1)
+    def srgb_to_linear(c)
+      c = c / 255.0
+      if c <= 0.04045
+        c / 12.92
+      else
+        ((c + 0.055) / 1.055)**2.4
+      end
+    end
+
     # Oklab → sRGB [r, g, b] (0..255)
     def oklab_to_srgb8(l, a, b)
       r, g, b_ = oklab_to_linear_rgb(l, a, b)
       [linear_to_srgb(r), linear_to_srgb(g), linear_to_srgb(b_)]
     end
+
+    # sRGB [r, g, b] (0..255) → Oklab [L, a, b]
+    def srgb8_to_oklab(r, g, b)
+      linear_rgb_to_oklab(srgb_to_linear(r), srgb_to_linear(g), srgb_to_linear(b))
+    end
+
+    # Oklab [L, a, b] → OkLCh [L, C, h] with h in degrees [0, 360)
+    def oklab_to_oklch(l, a, b)
+      c = Math.sqrt(a * a + b * b)
+      h = Math.atan2(b, a) * 180.0 / Math::PI
+      h += 360.0 if h.negative?
+      [l, c, h]
+    end
+
+    # OkLCh [L, C, h] (h in degrees) → Oklab [L, a, b]
+    def oklch_to_oklab(l, c, h)
+      rad = h * Math::PI / 180.0
+      [l, c * Math.cos(rad), c * Math.sin(rad)]
+    end
+
+    # sRGB [r, g, b] (0..255) → OkLCh [L, C, h] with h in degrees [0, 360)
+    def srgb8_to_oklch(r, g, b)
+      l, a, b_ = srgb8_to_oklab(r, g, b)
+      oklab_to_oklch(l, a, b_)
+    end
   end
 end

data/lib/okmain/sampler.rb

@@ -26,27 +26,37 @@ module Okmain
       block_size = compute_block_size(total)
 
       if block_size > 1
+        # Claude wanted to do this in Ruby for a more-exact rust match, because apparently image.shrink
+        # uses a slightly different algorithm, but an occasional 1 or 2 RGB value difference is a small
+        # price for the huge speedup in letting VIPS do it for us.
         image = image.shrink(block_size, block_size)
       end
 
       width = image.width
       height = image.height
 
+      # Claude's approach: Doing the colourspace translation ourselves
+      # ==============================================================
       # Extract float pixel data [r, g, b] in linear space
-      floats = image.write_to_memory.unpack("f*")
-      bands = image.bands
-      pixel_count = width * height
+      # floats = image.write_to_memory.unpack("f*")
+      # bands = image.bands
+      # pixel_count = width * height
 
-      pixels = Array.new(pixel_count)
-      i = 0
-      while i < pixel_count
-        offset = i * bands
-        r = floats[offset]
-        g = floats[offset + 1]
-        b = floats[offset + 2]
-        pixels[i] = Oklab.linear_rgb_to_oklab(r, g, b)
-        i += 1
-      end
+      # pixels = Array.new(pixel_count)
+      # i = 0
+      # while i < pixel_count
+      #   offset = i * bands
+      #   r = floats[offset]
+      #   g = floats[offset + 1]
+      #   b = floats[offset + 2]
+      #   pixels[i] = Oklab.linear_rgb_to_oklab(r, g, b)
+      #   i += 1
+      # end
+
+      # My approach: more than twice as fast to let VIPS do it for us
+      # =============================================================
+      image = image.colourspace(:oklab)
+      pixels = image.write_to_memory.unpack("f*").each_slice(3).to_a
 
       [pixels, width, height]
     end

data/lib/okmain/scorer.rb

@@ -10,7 +10,8 @@ module Okmain
     def score(centroids, assignments, mask, config)
       k = centroids.size
       n = assignments.size
-      mask_w = config.mask_weighted_counts_weight
+      mask_w = config.mask_weight
+      counts_w = config.mask_weighted_counts_weight
       chroma_w = config.chroma_weight
 
       # Weighted counts per centroid
@@ -37,7 +38,7 @@ module Okmain
       # Score each centroid
       scored = centroids.each_with_index.map do |centroid, idx|
         chroma = Math.sqrt(centroid[1] * centroid[1] + centroid[2] * centroid[2]) / MAX_SRGB_OKLAB_CHROMA
-        score = (1.0 - chroma_w) * weighted_counts[idx] + chroma_w * chroma
+        score = counts_w * weighted_counts[idx] + chroma_w * chroma
         [score, centroid]
       end
 

data/lib/okmain/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Okmain
-  VERSION = "0.1.0"
+  VERSION = "0.2.1"
 end

data/lib/okmain/xoshiro.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Okmain
+  # Xoshiro256++ PRNG, matching Rust's rand_xoshiro crate exactly.
+  # Seeding via SplitMix64 matches Rust's SeedableRng::seed_from_u64.
+  class Xoshiro256PlusPlus
+    MASK64 = (1 << 64) - 1
+
+    def initialize(seed)
+      # SplitMix64 seeding (matches Rust's SeedableRng::seed_from_u64)
+      sm = seed & MASK64
+      @s = Array.new(4) do
+        sm = (sm + 0x9e3779b97f4a7c15) & MASK64
+        z = sm
+        z = ((z ^ (z >> 30)) * 0xbf58476d1ce4e5b9) & MASK64
+        z = ((z ^ (z >> 27)) * 0x94d049bb133111eb) & MASK64
+        z ^ (z >> 31)
+      end
+    end
+
+    # Generate next u64
+    def next_u64
+      s = @s
+      result = (rotl(s[0] + s[3], 23) + s[0]) & MASK64
+      t = (s[1] << 17) & MASK64
+      s[2] ^= s[0]
+      s[3] ^= s[1]
+      s[1] ^= s[2]
+      s[0] ^= s[3]
+      s[2] ^= t
+      s[3] = rotl(s[3], 45)
+      result
+    end
+
+    # Uniform integer in 0...range, using Lemire's method (matching Rust's rand crate)
+    def random_range(range)
+      full = next_u64 * range
+      hi = full >> 64
+      lo = full & MASK64
+      if lo < range
+        threshold = (MASK64 - range + 1) % range # (2^64 - range) % range
+        while lo < threshold
+          full = next_u64 * range
+          hi = full >> 64
+          lo = full & MASK64
+        end
+      end
+      hi
+    end
+
+    # Uniform f32 in [0, 1), matching Rust's rand StandardUniform for f32.
+    # Xoshiro256++.next_u32() returns next_u64() >> 32 (upper bits).
+    # Then StandardUniform takes top 24 bits of the u32.
+    def random_f32
+      u64 = next_u64
+      u32 = u64 >> 32        # Rust's next_u32() for Xoshiro256++
+      (u32 >> 8).to_f / 16777216.0 # top 24 bits / 2^24
+    end
+
+    private
+
+    def rotl(x, k)
+      ((x << k) | (x >> (64 - k))) & MASK64
+    end
+  end
+end

data/lib/okmain.rb

@@ -5,6 +5,7 @@ require_relative "okmain/config"
 require_relative "okmain/oklab"
 require_relative "okmain/sampler"
 require_relative "okmain/distance_mask"
+require_relative "okmain/xoshiro"
 require_relative "okmain/kmeans"
 require_relative "okmain/scorer"
 
@@ -18,7 +19,7 @@ module Okmain
   # @return [Array<Array<Integer>>] up to 4 [r, g, b] arrays sorted by score
   def colors(input, config: Config.new)
     pixels, width, height = Sampler.sample(input)
-    mask = DistanceMask.compute(width, height)
+    mask = DistanceMask.compute(width, height, config.mask_saturated_threshold)
     centroids, assignments = KMeans.cluster(pixels)
     Scorer.score(centroids, assignments, mask, config)
   end

data/okmain.gemspec

@@ -13,9 +13,13 @@ Gem::Specification.new do |spec|
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
 
-  spec.files = Dir["lib/**/*.rb"] + ["okmain.gemspec", "README.md", "LICENSE-MIT", "LICENSE-APACHE"]
+  spec.files = Dir["lib/**/*.rb"] + ["okmain.gemspec", "README.md", "CHANGELOG.md", "LICENSE-MIT", "LICENSE-APACHE"]
   spec.require_paths = ["lib"]
 
   spec.add_dependency "ruby-vips", "~> 2.1"
+
+  spec.add_development_dependency "benchmark", "~> 0.4"
+  spec.add_development_dependency "rake", "~> 13.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: okmain
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Joshua Paine
@@ -23,10 +23,39 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: benchmark
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE-APACHE
 - LICENSE-MIT
 - README.md
@@ -38,6 +67,7 @@ files:
 - lib/okmain/sampler.rb
 - lib/okmain/scorer.rb
 - lib/okmain/version.rb
+- lib/okmain/xoshiro.rb
 - okmain.gemspec
 homepage: https://github.com/midnightmonster/okmain-ruby
 licenses:
@@ -46,6 +76,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/midnightmonster/okmain-ruby
   source_code_uri: https://github.com/midnightmonster/okmain-ruby
+  changelog_uri: https://github.com/midnightmonster/okmain-ruby/blob/main/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib
@@ -60,7 +91,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Extract dominant colors from images using adaptive K-means in Oklab space
 test_files: []