phash_native 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ec6f598c94538b3e622394dda53bd531269dfee837b969c7a1b7bf90a7a6c49e
+  data.tar.gz: 8fb3c0584f523de1ed12db2218fd076e8dcdf2bcf420414d3635a916e0859d46
+SHA512:
+  metadata.gz: 358aedff50d8260fb12d259c5bd91304df4d91066fd7eda31d1fecda082448bc457e0c1ccc13bbde357b7cb27ad0c56df90afae51ec8e771f08934f6123c6dda
+  data.tar.gz: 7b78da8bfc5aedff3f18b790ef4de832d3c489661a1a15a0212e5ef5a58a177eb856aebe23e6b83a6b3fb5d3e77ad28e01ca22bb74fa0dd365b294ed16fc15e1

data/README.md

@@ -0,0 +1,72 @@
+# phash_native
+
+A minimal, native, zero-dependency Ruby extension for computing [perceptual hashes (pHash)](https://www.phash.org/) from image files. Built entirely in C using `stb_image.h`, with no external dependencies outside the standard C library. Fast, simple, and does exactly one thing right.
+
+## Why this exists
+
+There are existing Ruby gems that attempt to do perceptual hashing (like `phashion`), but:
+
+- They're old and abandonware.
+- They rely on broken or outdated C++ libraries.
+- They fail to compile on modern systems.
+- They use external dependencies like FFTW or libjpeg, and end up being fragile and drifting out of compatibility over time.
+
+I needed something that worked. Something that could:
+
+- Read an image.
+- Compute a stable 64-bit perceptual hash based on DCT.
+- Compare hashes efficiently with Hamming distance.
+- Compile without screwing around with a million packages.
+
+So I wrote it.
+
+## Installation
+
+```bash
+gem install phash_native
+```
+
+Or in your Gemfile:
+
+```ruby
+gem "phash_native"
+```
+
+## Usage
+
+```ruby
+require "phash_native"
+
+hash = PhashNative.compute("some/image.png")
+# => 64-bit integer, e.g. 0x4f393c7331c7e7cc
+
+# Compare two images
+a = PhashNative.compute("image1.png")
+b = PhashNative.compute("image2.png")
+PhashNative.hamming(a, b)
+# => integer between 0 and 64
+```
+
+### Interpreting results
+
+The closer two hashes are (i.e. the smaller the Hamming distance), the more visually similar the images are. A Hamming distance of 0 means they're identical in structure. Under 10 is usually a strong match. Over 20? Probably different content.
+
+## Performance
+
+The native code uses:
+- A real 2D DCT on a 32×32 grayscale sample
+- A simple median threshold over the top-left 8×8 DCT block
+- Fast bitwise Hamming comparison (utilizes GCC intrinsics if available)
+
+This means it runs fast — fast enough for batch processing thousands of frames without sweating.
+
+## Limitations
+
+- Only supports images readable by `stb_image.h` (which covers PNG, JPEG, BMP, etc.) But what more could you need?
+- Always converts to grayscale and downscales to 32×32 internally
+- No audio or video support — this is just for still images
+- No SIMD or threading — yet. PRs welcome.
+
+---
+
+Yes, you could write your own. But now you don’t have to.

data/ext/phash_native/extconf.rb

@@ -0,0 +1,9 @@
+# ext/phash_native/extconf.rb
+require 'mkmf'
+
+# Clean up bogus flags (GCC will emit warnings otherwise)
+$CFLAGS.gsub!(/-Wno-self-assign/, '')
+$CFLAGS.gsub!(/-Wno-parentheses-equality/, '')
+$CFLAGS.gsub!(/-Wno-constant-logical-operand/, '')
+
+create_makefile('phash_native/phash_native')

data/ext/phash_native/phash_native.c

@@ -0,0 +1,112 @@
+// phash_native.c
+#include <ruby.h>
+#include <stdint.h>
+#include <stdlib.h>
+#include <math.h>
+#define STB_IMAGE_IMPLEMENTATION
+#include "stb_image.h"
+
+#define HASH_SIZE 8
+#define RESIZE_DIM 32
+
+static double dct_matrix[RESIZE_DIM][RESIZE_DIM];
+
+// Precompute DCT basis functions
+static void init_dct_matrix(void) {
+    for (int u = 0; u < RESIZE_DIM; u++) {
+        for (int x = 0; x < RESIZE_DIM; x++) {
+            double coef = (u == 0) ? sqrt(1.0 / RESIZE_DIM) : sqrt(2.0 / RESIZE_DIM);
+            dct_matrix[u][x] = coef * cos(((2 * x + 1) * u * M_PI) / (2.0 * RESIZE_DIM));
+        }
+    }
+}
+
+// Perform 2D DCT on grayscale matrix
+static void compute_dct(const double in[RESIZE_DIM][RESIZE_DIM], double out[RESIZE_DIM][RESIZE_DIM]) {
+    for (int u = 0; u < RESIZE_DIM; u++) {
+        for (int v = 0; v < RESIZE_DIM; v++) {
+            double sum = 0.0;
+            for (int x = 0; x < RESIZE_DIM; x++) {
+                for (int y = 0; y < RESIZE_DIM; y++) {
+                    sum += dct_matrix[u][x] * in[x][y] * dct_matrix[v][y];
+                }
+            }
+            out[u][v] = sum;
+        }
+    }
+}
+
+static VALUE compute_phash(VALUE self, VALUE filepath) {
+    Check_Type(filepath, T_STRING);
+    const char *filename = StringValueCStr(filepath);
+
+    int width, height, channels;
+    unsigned char *data = stbi_load(filename, &width, &height, &channels, 1); // 1 = grayscale
+    if (!data) {
+        rb_raise(rb_eRuntimeError, "Failed to load image: %s", filename);
+    }
+
+    double resized[RESIZE_DIM][RESIZE_DIM];
+    for (int y = 0; y < RESIZE_DIM; y++) {
+        for (int x = 0; x < RESIZE_DIM; x++) {
+            int src_x = x * width / RESIZE_DIM;
+            int src_y = y * height / RESIZE_DIM;
+            resized[y][x] = (double)data[src_y * width + src_x];
+        }
+    }
+
+    double dct[RESIZE_DIM][RESIZE_DIM];
+    compute_dct(resized, dct);
+
+    double sum = 0.0;
+    for (int y = 0; y < HASH_SIZE; y++) {
+        for (int x = 0; x < HASH_SIZE; x++) {
+            if (x == 0 && y == 0) continue; // Skip DC term
+            sum += dct[y][x];
+        }
+    }
+    double avg = sum / (HASH_SIZE * HASH_SIZE - 1);
+
+    uint64_t hash = 0;
+    for (int y = 0; y < HASH_SIZE; y++) {
+        for (int x = 0; x < HASH_SIZE; x++) {
+            if (x == 0 && y == 0) continue;
+            hash <<= 1;
+            hash |= (dct[y][x] > avg) ? 1 : 0;
+        }
+    }
+
+    stbi_image_free(data);
+    return ULL2NUM(hash);
+}
+
+// Hamming distance calculation
+#ifdef __GNUC__
+#include <x86intrin.h>
+static int hamming_distance(uint64_t a, uint64_t b) {
+    return __builtin_popcountll(a ^ b);
+}
+#else
+static int hamming_distance(uint64_t a, uint64_t b) {
+    uint64_t x = a ^ b;
+    int count = 0;
+    while (x) {
+        count += x & 1;
+        x >>= 1;
+    }
+    return count;
+}
+#endif
+
+static VALUE hamming_distance_rb(VALUE self, VALUE a_val, VALUE b_val) {
+    uint64_t a = NUM2ULL(a_val);
+    uint64_t b = NUM2ULL(b_val);
+    return INT2NUM(hamming_distance(a, b));
+}
+
+void Init_phash_native(void) {
+    init_dct_matrix();
+    VALUE mPhashNative = rb_define_module("PhashNative");
+    rb_define_singleton_method(mPhashNative, "compute", compute_phash, 1);
+    rb_define_singleton_method(mPhashNative, "hamming", hamming_distance_rb, 2);
+}