fast_thumbhash 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 79a84ccfbbffef86e7fa3657229d099c27acaeccb99f233a1eefec4147febb3c
-  data.tar.gz: a374ac8c3a50c7ba7fa189309612a5d41ba483e4e0d3ffcedb4eccf1250a9ba8
+  metadata.gz: d73528e540800828f98914de9bdbeb637eb6a1ea2564e2b48656e151ae0521a5
+  data.tar.gz: 0e8ee28b8872286957d0cc4afb894ccfa87a233391b2e1fcbcc89e603123d561
 SHA512:
-  metadata.gz: 7431add34523be78b8517c38f488e1548957ff0306af213bfca1ed679a4fb4f94378933f01a1ac3b24f6d651e18a8ad9ce3d3b80c7235dc5ee0f3aa5d1110cb9
-  data.tar.gz: 5d4f12735da45c54e055695cfae03de4d9122b9fc09dbf20f1329d17fcaaa5c435f6880ec83d2d001523dcf09ef668746bc66c6ef4b5a69e12dc66fd6f59be97
+  metadata.gz: 1d0964354d31b621773df344c005f6c190c7037a58f46396703c2c7f2805c54f3afe0244cbbdecbeb195f3d0b3c9b6cdf6453265103ebf95e4411dd7eaad159e
+  data.tar.gz: e104ab2a5e23f1e2a496647d83da5f6bc1e08e6f7692348ba3c4ff7fd6754d49bacdd5862b90281ec73b54bf629509a27cbdfbd2fc4467a2b1ae330115771236

data/.rubocop.yml

@@ -11,8 +11,29 @@ Style/StringLiteralsInInterpolation:
   Enabled: true
   EnforcedStyle: double_quotes
 
+Style/Documentation:
+  Enabled: false
+
 Layout/LineLength:
-  Max: 120
+  Enabled: false
 
-Style/Documentation:
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/BlockLength:
+  Enabled: false
+
+Metrics/ParameterLists:
+  Enabled: false
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
   Enabled: false
+
+Metrics/ModuleLength:
+  Enabled: false

data/Gemfile

@@ -6,7 +6,9 @@ source "https://rubygems.org"
 gemspec
 
 gem "bundler", "~> 2.0"
+gem "chunky_png", "~> 1.4"
 gem "rake", "~> 13.0"
 gem "rake-compiler", "~> 1.2"
 gem "rspec", "~> 3.0"
 gem "rubocop", "~> 1.21"
+gem "thumbhash", "0.0.1"

data/Gemfile.lock

@@ -1,13 +1,14 @@
 PATH
   remote: .
   specs:
-    fast_thumbhash (0.1.0)
+    fast_thumbhash (0.2.0)
       ffi
 
 GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.2)
+    chunky_png (1.4.0)
     diff-lcs (1.5.0)
     ffi (1.15.5)
     json (2.6.3)
@@ -46,18 +47,26 @@ GEM
     rubocop-ast (1.28.0)
       parser (>= 3.2.1.0)
     ruby-progressbar (1.13.0)
+    thumbhash (0.0.1)
     unicode-display_width (2.4.2)
 
 PLATFORMS
+  arm64-darwin-21
+  x86_64-darwin-18
   x86_64-darwin-20
+  x86_64-darwin-21
+  x86_64-darwin-22
+  x86_64-linux
 
 DEPENDENCIES
   bundler (~> 2.0)
+  chunky_png (~> 1.4)
   fast_thumbhash!
   rake (~> 13.0)
   rake-compiler (~> 1.2)
   rspec (~> 3.0)
   rubocop (~> 1.21)
+  thumbhash (= 0.0.1)
 
 BUNDLED WITH
    2.3.25

data/README.md

@@ -1,8 +1,10 @@
 # FastThumbhash
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/fast_thumbhash`. To experiment with that code, run `bin/console` for an interactive prompt.
+[![Ruby](https://github.com/datocms/fast_thumbhash/actions/workflows/main.yml/badge.svg)](https://github.com/datocms/fast_thumbhash/actions/workflows/main.yml)
 
-TODO: Delete this and the text above, and describe your gem
+FastThumbhash is a Ruby gem that provides a highly optimized implementation of the [ThumbHash algorithm](https://evanw.github.io/thumbhash/), a compact representation of an image placeholder for a smoother loading experience.
+
+To achieve these benefits, FastThumbhash is implemented as a Ruby C extension, which means that the core functionality of the ThumbHash algorithm is written in C for faster execution times compared to a pure Ruby implementation. This makes FastThumbhash ideal for applications or websites that require high-performance image processing.
 
 ## Installation
 
@@ -16,21 +18,107 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
 ## Usage
 
-TODO: Write usage instructions here
+Using the ChunkyPNG library to process the image, this example shows how to generate a thumbhash that can be stored alongside an image as well as the method to convert the hash into a data string for the image placeholder.
 
-## Development
+```ruby
+require "fast_thumbhash"
+require "chunky_png"
+require "base64"
+
+# load an image
+image = ChunkyPNG::Image.from_file("image.png")
+
+# convert the image into a base64-encoded thumbhash
+thumbhash = FastThumbhash.rgba_to_thumbhash(image.width, image.height, image.to_rgba_stream.unpack("C*"))
+
+puts thumbhash # => "rsYJLJZ4d4iAeIiAh5togIk3+A=="
+
+# convert the thumbhash back to an RGBA stream
+width, height, rgba = FastThumbhash.thumbhash_to_rgba(thumbhash, max_size: 32)
+
+# generate a placeholder image based on thumbhash
+placeholder = ChunkyPNG::Image.new(width, height, rgba.pack("C*").unpack("N*"))
+
+# save placeholder to file
+options = { compression: Zlib::BEST_COMPRESSION, filtering: ChunkyPNG::FILTER_PAETH, interlace: false }
+placeholder.save("placeholder.png", options)
+
+# generate a DataURL string for the pleaceholder
+thumbhash_image_blob = "data:image/png;base64,#{Base64.strict_encode64(thumbhash_image.to_blob(options))}"
+```
+
+### Additional Options
+
+This section covers additional options available for the `.thumbhash_to_rgba` method.
+
+##### `max_size`
+
+The max_size option allows you to request a thumbnail up to the specified size. This is the suggested option for most use cases.
+
+```ruby
+w, h, rgba = described_class.thumbhash_to_rgba(
+  thumbhash,
+  max_size: 32
+)
 
-After checking out the repo, run `bin/setup` to install dependencies.
+puts [w, h].inspect # => [10, 32]
+```
 
-Then, run `rake compile:fast_thumbhash` to compile the extensions.
+##### `homogeneous_transform` and `size`
 
-Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+The `homogeneous_transform` option allows you to apply a homogeneous transformation matrix when creating a thumbnail. The transformation matrix is a 3x3 array. This can be useful for applying roto-transformations to the thumbnail. The `size` option is useful to explicitly specify the width/height of the thumbnail when combined with the `homogeneous_transform` option to create a thumbnail with specific dimensions and transformations applied to it.
+
+
+```ruby
+w, h, rgba = described_class.thumbhash_to_rgba(
+  thumbhash,
+  size: [32, 32],
+  homogeneous_transform: [
+    [0.5, 0.0, 0.5],
+    [0.0, 1.0, 0.0],
+    [0.0, 0.0, 1.0]
+  ]
+)
+```
+
+##### `saturation`
+
+The `saturation` option adjusts the saturation of the thumbnail's colors. It accepts a value in the range of -100 to +100. A value of -100 will result in a grayscale image.
+
+```ruby
+w, h, rgba = described_class.thumbhash_to_rgba(
+  thumbhash,
+  max_size: 32,
+  saturation: -100
+)
+```
+
+##### `fill_mode`
+
+The `fill_mode` option specifies how to fill in any transparent areas in your image with a color of your choice. When `fill_mode` is `:solid`, you need to pass an additional `fill_color` option to specify the actual RGBA color to use. When `fill_mode` is `:blur`, the excess space will be filled with a blurred version of the original image itself.
+
+```ruby
+w, h, rgba = described_class.thumbhash_to_rgba(
+  thumbhash,
+  max_size: 32,
+  fill_mode: :solid,
+  fill_color: [255, 0, 0, 100],
+)
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
+## Releasing a new version
+
+First update the FastThumbhash::VERSION, then run `rake release`.
+
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/stefanoverna/thumbhash. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/stefanoverna/thumbhash/blob/master/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/datocms/fast_thumbhash. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/datocms/fast_thumbhash/blob/master/CODE_OF_CONDUCT.md).
 
 ## License
 
@@ -38,4 +126,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the FastThumbhash project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/stefanoverna/thumbhash/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the FastThumbhash project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/datocms/fast_thumbhash/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -8,8 +8,11 @@ require "rubocop/rake_task"
 RSpec::Core::RakeTask.new(:spec)
 RuboCop::RakeTask.new
 
-task default: %i[spec rubocop]
+Rake::Task[:build].enhance %i[spec rubocop]
+Rake::Task[:spec].enhance %i[compile:fast_thumbhash]
 
 Rake::ExtensionTask.new "fast_thumbhash" do |ext|
   ext.lib_dir = "lib"
 end
+
+task default: %i[spec rubocop]

data/ext/fast_thumbhash/fast_thumbhash.c

@@ -1,5 +1,503 @@
-#include <stdio.h>
+#include <fast_thumbhash.h>
+#include <stdlib.h>
+#include <math.h>
+#include <assert.h>
+#include <stdbool.h>
 
-void myfunc() {
-  printf("Hello from C!\n");
-}
+typedef struct encoded_channel
+{
+  double dc;
+  double *ac;
+  int ac_size;
+  double scale;
+} encoded_channel;
+
+encoded_channel encode_channel(double *channel, uint8_t nx, uint8_t ny, uint8_t w, uint8_t h)
+{
+  double dc = 0, scale = 0;
+  double *ac = (double *)malloc(nx * ny * sizeof(double));
+  double *fx = (double *)malloc(w * sizeof(double));
+  int ac_length = 0;
+
+  for (int cy = 0; cy < ny; cy++)
+  {
+    for (int cx = 0; cx * ny < nx * (ny - cy); cx++)
+    {
+      double f = 0;
+
+      for (int x = 0; x < w; x++)
+      {
+        fx[x] = cos(M_PI / w * cx * (x + 0.5));
+      }
+
+      for (int y = 0; y < h; y++)
+      {
+        double fy = cos(M_PI / h * cy * (y + 0.5));
+        for (int x = 0; x < w; x++)
+        {
+          f += channel[x + y * w] * fx[x] * fy;
+        }
+      }
+
+      f /= w * h;
+
+      if (cx || cy)
+      {
+        ac[ac_length++] = f;
+        scale = fmax(scale, fabsl(f));
+      }
+      else
+      {
+        dc = f;
+      }
+    }
+  }
+
+  if (scale)
+  {
+    for (int i = 0; i < ac_length; i++)
+    {
+      ac[i] = 0.5 + 0.5 / scale * ac[i];
+    }
+  }
+
+  free(fx);
+
+  return (encoded_channel){dc, ac, ac_length, scale};
+}
+
+void write_varying_factors(double *ac, int ac_size, uint8_t *thumbhash, uint8_t *ac_index) {
+  for (int i = 0; i < ac_size; i++) {
+    uint8_t index = (*ac_index) >> 1;
+    thumbhash[index] |= (uint8_t) roundf(15.0 * ac[i]) << (((*ac_index)++ & 1) << 2);
+  }
+}
+
+void rgba_to_thumbhash(uint8_t w, uint8_t h, uint8_t *rgba, uint8_t *thumbhash)
+{
+  assert(w <= 100);
+  assert(h <= 100);
+
+  // Determine the average color
+  double avg_r = 0, avg_g = 0, avg_b = 0, avg_a = 0;
+
+  for (int i = 0, j = 0; i < w * h; i++, j += 4)
+  {
+    double alpha = (double)rgba[j + 3] / 255.0;
+    avg_r += alpha / 255.0 * rgba[j];
+    avg_g += alpha / 255.0 * rgba[j + 1];
+    avg_b += alpha / 255.0 * rgba[j + 2];
+    avg_a += alpha;
+  }
+
+  if (avg_a)
+  {
+    avg_r /= avg_a;
+    avg_g /= avg_a;
+    avg_b /= avg_a;
+  }
+
+  bool has_alpha = avg_a < w * h;
+  uint8_t l_limit = has_alpha ? 5 : 7; // Use fewer luminance bits if there's alpha
+  uint8_t lx = fmax(1, roundf((double)l_limit * w / fmax(w, h)));
+  uint8_t ly = fmax(1, roundf((double)l_limit * h / fmax(w, h)));
+
+  double *l = (double *)malloc(w * h * sizeof(double)); // luminance
+  double *p = (double *)malloc(w * h * sizeof(double)); // yellow - blue
+  double *q = (double *)malloc(w * h * sizeof(double)); // red - green
+  double *a = (double *)malloc(w * h * sizeof(double)); // alpha
+
+  // Convert the image from RGBA to LPQA (composite atop the average color)
+  for (int i = 0, j = 0; i < w * h; i++, j += 4)
+  {
+    double alpha = (double)rgba[j + 3] / 255;
+    double r = avg_r * (1.0 - alpha) + alpha / 255.0 * (double)rgba[j];
+    double g = avg_g * (1.0 - alpha) + alpha / 255.0 * (double)rgba[j + 1];
+    double b = avg_b * (1.0 - alpha) + alpha / 255.0 * (double)rgba[j + 2];
+    l[i] = (r + g + b) / 3;
+    p[i] = (r + g) / 2 - b;
+    q[i] = r - g;
+    a[i] = alpha;
+  }
+
+  // Encode using the DCT into DC (constant) and normalized AC (varying) terms
+  encoded_channel el = encode_channel(l, fmax(3, lx), fmax(3, ly), w, h);
+  encoded_channel ep = encode_channel(p, 3, 3, w, h);
+  encoded_channel eq = encode_channel(q, 3, 3, w, h);
+  encoded_channel ea = has_alpha ? encode_channel(a, 5, 5, w, h) : (encoded_channel){1.0, NULL, 0, 1.0};
+
+  free(l);
+  free(p);
+  free(q);
+  free(a);
+
+  // Write the constants
+  bool is_landscape = w > h;
+  u_int32_t header24 = (u_int32_t)roundf(63.0 * el.dc) | ((u_int32_t)roundf(31.5 + 31.5 * ep.dc) << 6) | ((u_int32_t)roundf(31.5 + 31.5 * eq.dc) << 12) | ((u_int32_t)roundf(31.0 * el.scale) << 18) | (has_alpha << 23);
+  u_int32_t header16 = (is_landscape ? ly : lx) | ((u_int16_t)roundf(63.0 * ep.scale) << 3) | ((u_int16_t)roundf(63.0 * eq.scale) << 9) | (is_landscape << 15);
+
+  thumbhash[0] = (uint8_t)(header24 & 0xff);
+  thumbhash[1] = (uint8_t)((header24 >> 8) & 0xff);
+  thumbhash[2] = (uint8_t)(header24 >> 16);
+  thumbhash[3] = (uint8_t)(header16 & 0xff);
+  thumbhash[4] = (uint8_t)(header16 >> 8);
+
+  if (has_alpha) {
+    thumbhash[5] = (uint8_t) roundf(15.0 * ea.dc) | ((uint8_t) roundf(15.0 * ea.scale) << 4);
+  }
+
+  uint8_t ac_start = has_alpha ? 6 : 5;
+  uint8_t ac_index = 0;
+
+  write_varying_factors(el.ac, el.ac_size, thumbhash + ac_start, &ac_index);
+  write_varying_factors(ep.ac, ep.ac_size, thumbhash + ac_start, &ac_index);
+  write_varying_factors(eq.ac, eq.ac_size, thumbhash + ac_start, &ac_index);
+
+  if (has_alpha) {
+    write_varying_factors(ea.ac, ea.ac_size, thumbhash + ac_start, &ac_index);
+  }
+
+  free(el.ac);
+  free(ep.ac);
+  free(eq.ac);
+
+  if (has_alpha) {
+    free(ea.ac);
+  }
+}
+
+double *decode_channel(uint8_t nx, uint8_t ny, double scale, uint8_t *hash, uint8_t ac_start, uint8_t *ac_index)
+{
+  double *ac = (double *)malloc(nx * ny * sizeof(double));
+  int i = 0;
+  for (int cy = 0; cy < ny; cy++)
+  {
+    for (int cx = cy ? 0 : 1; cx * ny < nx * (ny - cy); cx++)
+    {
+      double bit = (hash[ac_start + (*ac_index >> 1)] >> (((*ac_index)++ & 1) << 2)) & 15;
+      ac[i++] = (bit / 7.5 - 1) * scale;
+    }
+  }
+
+  return ac;
+}
+
+double thumbhash_to_approximate_aspect_ratio(uint8_t *hash)
+{
+  uint8_t has_alpha = (hash[2] & 0x80) != 0;
+  uint8_t l_max = has_alpha ? 5 : 7;
+  uint8_t l_min = hash[3] & 7;
+  uint8_t is_landscape = (hash[4] & 0x80) != 0;
+  uint8_t lx = is_landscape ? l_max : l_min;
+  uint8_t ly = is_landscape ? l_min : l_max;
+
+  return (double)lx / (double)ly;
+}
+
+void thumb_size(uint8_t *hash, uint8_t max_size, uint8_t *size)
+{
+  double ratio = thumbhash_to_approximate_aspect_ratio(hash);
+
+  size[0] = roundf(ratio > 1 ? max_size : max_size * ratio);
+  size[1] = roundf(ratio > 1 ? max_size / ratio : max_size);
+}
+
+void rgb2hsv(uint8_t *rgb, float *hsv)
+{
+  float min, max, delta;
+
+  float r = rgb[0] / 255.0;
+  float g = rgb[1] / 255.0;
+  float b = rgb[2] / 255.0;
+
+  min = r < g ? r : g;
+  min = min < b ? min : b;
+
+  max = r > g ? r : g;
+  max = max > b ? max : b;
+
+  hsv[2] = max;
+
+  delta = max - min;
+
+  if (delta < 0.00001)
+  {
+    hsv[1] = 0;
+    hsv[0] = 0; // undefined, maybe nan?
+    return;
+  }
+  if (max > 0.0)
+  {                         // NOTE: if Max is == 0, this divide would cause a crash
+    hsv[1] = (delta / max); // s
+  }
+  else
+  {
+    // if max is 0, then r = g = b = 0
+    // s = 0, h is undefined
+    hsv[1] = 0.0;
+    hsv[0] = NAN; // its now undefined
+    return;
+  }
+
+  if (r >= max)               // > is bogus, just keeps compilor happy
+    hsv[0] = (g - b) / delta; // between yellow & magenta
+  else if (g >= max)
+    hsv[0] = 2.0 + (b - r) / delta; // between cyan & yellow
+  else
+    hsv[0] = 4.0 + (r - g) / delta; // between magenta & cyan
+
+  hsv[0] *= 60.0; // degrees
+
+  if (hsv[0] < 0.0)
+    hsv[0] += 360.0;
+}
+
+void hsv2rgb(float *hsv, uint8_t *rgb)
+{
+  float hh, p, q, t, ff;
+  long i;
+
+  if (hsv[1] <= 0.0)
+  { // < is bogus, just shuts up warnings
+    rgb[0] = hsv[2] * 255.0;
+    rgb[1] = hsv[2] * 255.0;
+    rgb[2] = hsv[2] * 255.0;
+    return;
+  }
+
+  hh = hsv[0];
+
+  if (hh >= 360.0)
+    hh = 0.0;
+
+  hh /= 60.0;
+
+  i = (long)hh;
+
+  ff = hh - i;
+  p = hsv[2] * (1.0 - hsv[1]);
+  q = hsv[2] * (1.0 - (hsv[1] * ff));
+  t = hsv[2] * (1.0 - (hsv[1] * (1.0 - ff)));
+
+  switch (i)
+  {
+  case 0:
+    rgb[0] = hsv[2] * 255.0;
+    rgb[1] = t * 255.0;
+    rgb[2] = p * 255.0;
+    return;
+  case 1:
+    rgb[0] = q * 255.0;
+    rgb[1] = hsv[2] * 255.0;
+    rgb[2] = p * 255.0;
+    return;
+  case 2:
+    rgb[0] = p * 255.0;
+    rgb[1] = hsv[2] * 255.0;
+    rgb[2] = t * 255.0;
+    return;
+
+  case 3:
+    rgb[0] = p * 255.0;
+    rgb[1] = q * 255.0;
+    rgb[2] = hsv[2] * 255.0;
+    return;
+  case 4:
+    rgb[0] = t * 255.0;
+    rgb[1] = p * 255.0;
+    rgb[2] = hsv[2] * 255.0;
+    return;
+  case 5:
+  default:
+    rgb[0] = hsv[2] * 255.0;
+    rgb[1] = p * 255.0;
+    rgb[2] = q * 255.0;
+    return;
+  }
+}
+
+/**
+ * Decodes a ThumbHash to an RGBA image. RGB is not be premultiplied by A.
+ */
+void thumbhash_to_rgba(
+  uint8_t *hash,
+  uint8_t w,
+  uint8_t h,
+  enum FillMode fill_mode,
+  uint8_t *fill_color,
+  double *homogeneous_transform,
+  int saturation,
+  uint8_t *rgba
+)
+{
+  // Read the constants
+  u_int32_t header24 = hash[0] | (hash[1] << 8) | (hash[2] << 16);
+  u_int32_t header16 = hash[3] | (hash[4] << 8);
+  double l_dc = (double)(header24 & 63) / 63;
+  double p_dc = (double)((header24 >> 6) & 63) / 31.5 - 1;
+  double q_dc = (double)((header24 >> 12) & 63) / 31.5 - 1;
+  double l_scale = (double)((header24 >> 18) & 31) / 31;
+  bool has_alpha = (header24 >> 23) != 0;
+  double p_scale = (double)((header16 >> 3) & 63) / 63;
+  double q_scale = (double)((header16 >> 9) & 63) / 63;
+  bool is_landscape = (header16 >> 15) != 0;
+  uint8_t lx = fmax(3, is_landscape ? has_alpha ? 5 : 7 : header16 & 7);
+  uint8_t ly = fmax(3, is_landscape ? header16 & 7 : has_alpha ? 5 : 7);
+  double a_dc = (double)has_alpha ? (hash[5] & 15) / 15 : 1;
+  double a_scale = (double)(hash[5] >> 4) / 15;
+
+  // Read the varying factors (boost saturation by 1.25x to compensate for quantization)
+  uint8_t ac_start = has_alpha ? 6 : 5;
+  uint8_t ac_index = 0;
+
+  double *l_ac = decode_channel(lx, ly, l_scale, hash, ac_start, &ac_index);
+  double *p_ac = decode_channel(3, 3, p_scale * 1.25, hash, ac_start, &ac_index);
+  double *q_ac = decode_channel(3, 3, q_scale * 1.25, hash, ac_start, &ac_index);
+  double *a_ac = has_alpha ? decode_channel(5, 5, a_scale, hash, ac_start, &ac_index) : NULL;
+
+  // Decode using the DCT into RGB
+  double fx[7];
+  double fy[7];
+  u_int32_t i = 0;
+
+  for (uint8_t ry = 0; ry < h; ry++)
+  {
+    for (uint8_t rx = 0; rx < w; rx++, i += 4)
+    {
+
+      double px = ((double)rx + 0.5) / w;
+      double py = ((double)ry + 0.5) / h;
+
+      double x = px;
+      double y = py;
+
+      if (homogeneous_transform)
+      {
+        x = homogeneous_transform[0] * px + homogeneous_transform[1] * py + homogeneous_transform[2];
+        y = homogeneous_transform[3] * px + homogeneous_transform[4] * py + homogeneous_transform[5];
+      }
+
+      double r, g, b, a;
+
+      if (fill_mode == BLUR) {
+        if (x < 0)
+        {
+          x = 0;
+        }
+        else if (x >= 1)
+        {
+          x = 1;
+        }
+        else if (y < 0)
+        {
+          y = 0;
+        }
+        else if (y >= 1)
+        {
+          y = 1;
+        }
+      }
+
+      if (x >= 0 && x <= 1.0 && y >= 0 && y <= 1.0) {
+        double l = l_dc, p = p_dc, q = q_dc;
+        a = a_dc;
+
+        // Precompute the coefficients
+        for (int cx = 0, n = fmax(lx, has_alpha ? 5 : 3); cx < n; cx++)
+        {
+          fx[cx] = cos(M_PI * x * cx);
+        }
+        for (int cy = 0, n = fmax(ly, has_alpha ? 5 : 3); cy < n; cy++)
+        {
+          fy[cy] = cos(M_PI * y * cy);
+        }
+
+        // Decode L
+        double fy2;
+        for (int cy = 0, j = 0; cy < ly; cy++)
+        {
+          fy2 = fy[cy] * 2;
+          for (int cx = cy ? 0 : 1; cx * ly < lx * (ly - cy); cx++, j++)
+          {
+            l += l_ac[j] * fx[cx] * fy2;
+          }
+        }
+
+        // Decode P and Q
+        for (int cy = 0, j = 0; cy < 3; cy++)
+        {
+          fy2 = fy[cy] * 2;
+          for (int cx = cy ? 0 : 1; cx < 3 - cy; cx++, j++)
+          {
+            double f = fx[cx] * fy2;
+            p += p_ac[j] * f;
+            q += q_ac[j] * f;
+          }
+        }
+
+        // Decode A
+        if (has_alpha)
+        {
+          for (int cy = 0, j = 0; cy < 5; cy++)
+          {
+            fy2 = fy[cy] * 2;
+            for (int cx = cy ? 0 : 1; cx < 5 - cy; cx++, j++)
+            {
+              a += a_ac[j] * fx[cx] * fy2;
+            }
+          }
+        }
+
+        // Convert to RGB
+        b = l - 2.0 / 3.0 * p;
+        r = (3.0 * l - b + q) / 2.0;
+        g = r - q;
+      } else {
+        r = 0;
+        g = 0;
+        b = 0;
+        a = 0;
+      }
+
+      uint_fast8_t top[4] = {
+        fmax(0, 255 * fmin(1, r)),
+        fmax(0, 255 * fmin(1, g)),
+        fmax(0, 255 * fmin(1, b)),
+        fmax(0, 255 * fmin(1, a))
+      };
+
+      if (fill_mode == SOLID) {
+        // Alpha-blending
+        double top_alpha = (double) top[3] / 255.0;
+
+        rgba[i]   = roundf(top[0] * top_alpha + fill_color[0] * (1.0 - top_alpha));
+        rgba[i+1] = roundf(top[1] * top_alpha + fill_color[1] * (1.0 - top_alpha));
+        rgba[i+2] = roundf(top[2] * top_alpha + fill_color[2] * (1.0 - top_alpha));
+        rgba[i+3] = roundf(top[3] * top_alpha + fill_color[3] * (1.0 - top_alpha));
+      } else {
+        rgba[i]   = top[0];
+        rgba[i+1] = top[1];
+        rgba[i+2] = top[2];
+        rgba[i+3] = top[3];
+      }
+
+      if (saturation)
+      {
+        float hsv[3] = {0};
+        rgb2hsv(rgba + i, hsv);
+        float mult = ((float) saturation + 100.0f) / 200.0f * 1.4f;
+        hsv[1] = fminf(fmaxf(hsv[1] * mult, 0), 1.0f);
+        hsv2rgb(hsv, rgba + i);
+      }
+    }
+  }
+
+  free(l_ac);
+  free(p_ac);
+  free(q_ac);
+
+  if (has_alpha)
+  {
+    free(a_ac);
+  }
+}

data/ext/fast_thumbhash/fast_thumbhash.h

@@ -1 +1,36 @@
-void myfunc();
+#ifndef __FAST_THUMBHASH_H__
+#define __FAST_THUMBHASH_H__
+
+#include <stdint.h>
+
+enum FillMode {
+  NO_FILL = 0,
+  SOLID = 1,
+  BLUR = 2,
+};
+
+void rgba_to_thumbhash(
+  uint8_t w,
+  uint8_t h,
+  uint8_t *rgba,
+  uint8_t *thumbhash
+);
+
+void thumb_size(
+  uint8_t *hash,
+  uint8_t max_size,
+  uint8_t *size
+);
+
+void thumbhash_to_rgba(
+  uint8_t *hash,
+  uint8_t w,
+  uint8_t h,
+  enum FillMode fill_mode,
+  uint8_t *fill_color,
+  double *homogeneous_transform,
+  int saturation,
+  uint8_t *rgba
+);
+
+#endif

data/fast_thumbhash.gemspec

@@ -8,9 +8,9 @@ Gem::Specification.new do |spec|
   spec.authors = ["Stefano Verna"]
   spec.email = ["s.verna@datocms.com"]
 
-  spec.summary = "Ruby bindings for encoding/decoding thumbhash"
-  spec.description = "Ruby bindings for encoding/decoding thumbhash"
-  spec.homepage = "https://github.com/stefanoverna/thumbhash"
+  spec.summary = "Ruby C extension to encode/decode ThumbHash"
+  spec.description = "Provides a highly optimized implementation of the ThumbHash algorithm, a compact representation of an image placeholder for a smoother loading experience"
+  spec.homepage = "https://github.com/datocms/fast_thumbhash"
   spec.license = "MIT"
   spec.required_ruby_version = ">= 2.6.0"
 

data/lib/fast_thumbhash/version.rb

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

data/lib/fast_thumbhash.rb

@@ -4,13 +4,152 @@ require "ffi"
 require_relative "fast_thumbhash/version"
 
 module FastThumbhash
-  def self.myfunc
-    Library.myfunc
+  def self.thumbhash_to_rgba(
+    thumbhash,
+    max_size: nil,
+    size: nil,
+    fill_mode: :no_fill,
+    fill_color: nil,
+    homogeneous_transform: nil,
+    saturation: 0
+  )
+    binary_thumbhash_to_rgba(
+      Base64.decode64(thumbhash),
+      max_size: max_size,
+      size: size,
+      fill_mode: fill_mode,
+      fill_color: fill_color,
+      homogeneous_transform: homogeneous_transform,
+      saturation: saturation
+    )
+  end
+
+  def self.binary_thumbhash_to_rgba(
+    binary_thumbhash,
+    max_size: nil,
+    size: nil,
+    fill_mode: :no_fill,
+    fill_color: nil,
+    homogeneous_transform: nil,
+    saturation: 0
+  )
+    !max_size.nil? ^ !size.nil? or
+      raise ArgumentError, "Pass either the `max_size` option, or an explicit `size`"
+
+    %i[solid blur no_fill].include?(fill_mode) or
+      raise ArgumentError, "Invalid `fill_mode` option"
+
+    fill_color_pointer =
+      if fill_mode == :solid
+        fill_color or
+          raise ArgumentError, "`fill_color` is required if fill_mode = :solid"
+
+        fill_color.length == 4 or
+          raise ArgumentError, "You need to pass [r, g, b, a] to the `fill_color` option"
+
+        FFI::MemoryPointer.new(:uint8, 4).tap do |p|
+          p.write_array_of_uint8(fill_color)
+        end
+      end
+
+    transform_pointer =
+      if homogeneous_transform
+        (homogeneous_transform.size == 3 && homogeneous_transform.all? { |row| row.size == 3 }) or
+          raise ArgumentError, "`homogeneous_transform` option must be a 3x3 matrix"
+
+        FFI::MemoryPointer.new(:double, 6).tap do |p|
+          p.write_array_of_double(
+            [
+              homogeneous_transform[0][0],
+              homogeneous_transform[0][1],
+              homogeneous_transform[0][2],
+              homogeneous_transform[1][0],
+              homogeneous_transform[1][1],
+              homogeneous_transform[1][2]
+            ]
+          )
+        end
+      end
+
+    thumbhash_pointer = FFI::MemoryPointer.new(:uint8, binary_thumbhash.size)
+    thumbhash_pointer.put_array_of_uint8(0, binary_thumbhash.unpack("C*"))
+
+    width, height =
+      if size
+        size.length == 2 or
+          raise ArgumentError, "You need to pass [width, height] to the `size` option"
+
+        size.all? { |dimension| dimension < 100 } or
+          raise ArgumentError, "Cannot generate images bigger then 100 pixels"
+
+        size
+      else
+        max_size <= 100 or
+          raise ArgumentError, "Cannot generate images bigger then 100 pixels"
+
+        thumb_size_pointer = FFI::MemoryPointer.new(:uint8, 2)
+        Library.thumb_size(thumbhash_pointer, max_size, thumb_size_pointer)
+        thumb_size_pointer.read_array_of_uint8(2)
+      end
+
+    rgba_size = width * height * 4
+    rgba_pointer = FFI::MemoryPointer.new(:uint8, rgba_size)
+    Library.thumbhash_to_rgba(
+      thumbhash_pointer,
+      width,
+      height,
+      fill_mode.to_sym,
+      fill_color_pointer,
+      transform_pointer,
+      saturation,
+      rgba_pointer
+    )
+
+    [width, height, rgba_pointer.read_array_of_uint8(rgba_size)]
+  ensure
+    fill_color_pointer&.free
+    transform_pointer&.free
+    thumbhash_pointer&.free
+    thumb_size_pointer&.free
+    rgba_pointer&.free
+  end
+
+  def self.rgba_to_thumbhash(width, height, rgba)
+    Base64.strict_encode64(rgba_to_binary_thumbhash(width, height, rgba))
+  end
+
+  def self.rgba_to_binary_thumbhash(width, height, rgba)
+    (width <= 100 && height <= 100) or
+      raise ArgumentError, "Encoding an image larger than 100x100 is slow with no benefit"
+
+    rgba_pointer = FFI::MemoryPointer.new(:uint8, rgba.size)
+    rgba_pointer.put_array_of_uint8(0, rgba)
+
+    thumbhash_pointer = FFI::MemoryPointer.new(:uint8, 25)
+
+    Library.rgba_to_thumbhash(width, height, rgba_pointer, thumbhash_pointer)
+
+    result = thumbhash_pointer.read_array_of_uint8(25)
+    result.pop while result.last.zero?
+
+    result.pack("C*")
+  ensure
+    rgba_pointer&.free
+    thumbhash_pointer&.free
   end
 
   module Library
     extend FFI::Library
     ffi_lib File.join(File.expand_path(__dir__), "fast_thumbhash.#{RbConfig::CONFIG["DLEXT"]}")
-    attach_function :myfunc, [], :void
+
+    enum :fill_mode, [
+      :no_fill, 0,
+      :solid,
+      :blur
+    ]
+
+    attach_function :thumb_size, %i[pointer uint8 pointer], :size_t
+    attach_function :thumbhash_to_rgba, %i[pointer uint8 uint8 fill_mode pointer pointer int pointer], :void
+    attach_function :rgba_to_thumbhash, %i[uint8 uint8 pointer pointer], :void
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fast_thumbhash
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Stefano Verna
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-04-05 00:00:00.000000000 Z
+date: 2023-04-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
@@ -24,7 +24,8 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Ruby bindings for encoding/decoding thumbhash
+description: Provides a highly optimized implementation of the ThumbHash algorithm,
+  a compact representation of an image placeholder for a smoother loading experience
 email:
 - s.verna@datocms.com
 executables: []
@@ -45,12 +46,12 @@ files:
 - fast_thumbhash.gemspec
 - lib/fast_thumbhash.rb
 - lib/fast_thumbhash/version.rb
-homepage: https://github.com/stefanoverna/thumbhash
+homepage: https://github.com/datocms/fast_thumbhash
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/stefanoverna/thumbhash
-  source_code_uri: https://github.com/stefanoverna/thumbhash
+  homepage_uri: https://github.com/datocms/fast_thumbhash
+  source_code_uri: https://github.com/datocms/fast_thumbhash
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
@@ -70,5 +71,5 @@ requirements: []
 rubygems_version: 3.1.6
 signing_key:
 specification_version: 4
-summary: Ruby bindings for encoding/decoding thumbhash
+summary: Ruby C extension to encode/decode ThumbHash
 test_files: []