rublurhash 0.0.1

data/ext/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "rublurhash"
+version = "0.0.1"
+edition = "2024"
+authors = ["Kitait Makoto <KitaitiMakoto@gmail.com>"]
+publish = false
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+magnus = ">= 0.8.2"
+blurhash-core = { version = "0.1.0", features = ["simd", "gpu"] }
+grey-knights = "=0.1.1"

data/ext/src/lib.rs

@@ -0,0 +1,243 @@
+use grey_knights::memory_view::{
+    Builder, Entry, Flags, FlagsChainable, ValidatedMemoryView, register,
+};
+use magnus::{
+    Attr, Module, Object, RArray, RClass, RModule, RString, Ruby, TryConvert, Value,
+    encoding::EncodingCapable,
+    error::IntoError,
+    function,
+    scan_args::{get_kwargs, scan_args},
+    value::ReprValue,
+};
+use std::num::TryFromIntError;
+
+enum Error {
+    Arg(String),
+    Runtime(String),
+    Magnus(magnus::Error),
+    Blurhash(blurhash_core::BlurhashError),
+}
+
+impl magnus::error::IntoError for Error {
+    fn into_error(self, ruby: &Ruby) -> magnus::Error {
+        use Error::*;
+
+        match self {
+            Arg(msg) => magnus::Error::new(ruby.exception_arg_error(), msg),
+            Runtime(msg) => magnus::Error::new(ruby.exception_runtime_error(), msg),
+            Magnus(err) => err,
+            Blurhash(err) => magnus::Error::new(ruby.exception_runtime_error(), format!("{}", err)),
+        }
+    }
+}
+
+impl From<magnus::Error> for Error {
+    fn from(value: magnus::Error) -> Self {
+        Self::Magnus(value)
+    }
+}
+
+impl From<blurhash_core::BlurhashError> for Error {
+    fn from(value: blurhash_core::BlurhashError) -> Self {
+        Self::Blurhash(value)
+    }
+}
+
+impl From<TryFromIntError> for Error {
+    fn from(value: TryFromIntError) -> Self {
+        Self::Arg(format!("{}", value))
+    }
+}
+
+type Result<T> = std::result::Result<T, Error>;
+
+fn encode(ruby: &Ruby, arguments: &[Value]) -> Result<String> {
+    let args = scan_args::<(Value,), (), (), (), _, ()>(arguments)?;
+    let kws = get_kwargs::<_, (u32, u32), (Option<Option<u32>>, Option<Option<u32>>), ()>(
+        args.keywords,
+        &["components_x", "components_y"],
+        &["width", "height"],
+    )?;
+    let (components_x, components_y) = kws.required;
+    let (width, height) = kws.optional;
+    let width = width.flatten();
+    let height = height.flatten();
+    match (width, height) {
+        (None, None) => {
+            let pxs = args.required.0;
+            let memview = ValidatedMemoryView::<u8>::new(
+                pxs,
+                Flags::format().multi_dimensional().row_major(),
+            )?;
+            // TODO: Support ndim == 2 && format == "CCC"
+            if memview.ndim() != 3_isize {
+                return Err(Error::Arg("ndim must be 3".into()));
+            }
+            let shape = memview
+                .shape()
+                .ok_or_else(|| Error::Arg("shape must not be null".into()))?;
+            if shape.len() != 3 {
+                return Err(Error::Arg("shape length must be 3".into()));
+            }
+            if shape[2] != 3 {
+                return Err(Error::Arg("shape[2] must be 3".into()));
+            }
+            if !memview.is_row_major_contiguous() {
+                return Err(Error::Arg("must be row-major contiguous".into()));
+            }
+            if memview.format().is_some() {
+                let item_desc = memview.item_desc()?;
+                if item_desc.len() != 1 {
+                    return Err(Error::Arg(format!(
+                        "item_desc length must be 1, but was {}",
+                        item_desc.len()
+                    )));
+                }
+                let component = item_desc
+                    .into_iter()
+                    .next()
+                    .expect("item_desc length is exactly 1");
+                if component.format != 'C' || component.repeat != 1 {
+                    return Err(Error::Arg(format!(
+                        "format must be NULL or \"C\", but was {}",
+                        component.format
+                    )));
+                }
+            }
+            blurhash_core::gpu::encode_gpu(
+                memview.data(),
+                u32::try_from(shape[1])?,
+                u32::try_from(shape[0])?,
+                components_x,
+                components_y,
+            )
+            .map_err(Error::Blurhash)
+        }
+        (Some(width), Some(height)) => {
+            let pixels = arguments[0];
+            if RArray::from_value(pixels).is_some() {
+                blurhash_core::gpu::encode_gpu(
+                    Vec::<u8>::try_convert(pixels)?.as_slice(),
+                    width,
+                    height,
+                    components_x,
+                    components_y,
+                )
+            } else if let Some(pxs) = RString::from_value(pixels) {
+                if pxs.enc_get() != ruby.ascii8bit_encindex() {
+                    return Err(Error::Arg("Not ASCII-8BIT".into()));
+                }
+                blurhash_core::gpu::encode_gpu(
+                    unsafe { pxs.as_slice() },
+                    width,
+                    height,
+                    components_x,
+                    components_y,
+                )
+            } else {
+                return Err(Error::Arg(format!(
+                    "First argument must be Array or String, but given: {}",
+                    pixels.class()
+                )));
+            }
+            .map_err(Error::Blurhash)
+        }
+        _ => Err(Error::Arg(
+            "Both width and height are required if given".into(),
+        )),
+    }
+}
+
+struct ImageString();
+
+impl ImageString {
+    fn init(ruby: &Ruby, rb_self: Value, width: u32, height: u32) -> Result<()> {
+        let s = RString::from_value(rb_self)
+            .ok_or_else(|| Error::Runtime("Failed to create new instance of ImageString".into()))?;
+        s.ivar_set("@width", ruby.integer_from_u64(width.into()))?;
+        s.ivar_set("@height", ruby.integer_from_u64(height.into()))?;
+        s.freeze();
+
+        Ok(())
+    }
+}
+
+impl Entry for ImageString {
+    type PrivateData = ();
+
+    fn get(
+        obj: Value,
+        view: &mut Builder<Self::PrivateData>,
+        flags: &Flags,
+    ) -> std::result::Result<(), magnus::Error> {
+        let ruby = Ruby::get_with(obj);
+        if flags.has_writable() {
+            return Err(magnus::Error::new(
+                ruby.exception_arg_error(),
+                "Cannot be writable",
+            ));
+        }
+        if flags.has_indirect() {
+            return Err(magnus::Error::new(
+                ruby.exception_arg_error(),
+                "Cannot be indirect",
+            ));
+        }
+        let Some(rstring) = RString::from_value(obj) else {
+            return Err(magnus::Error::new(
+                ruby.exception_type_error(),
+                "Invalid type",
+            ));
+        };
+        let width: isize = rstring.ivar_get("@width")?;
+        let height: isize = rstring.ivar_get("@height")?;
+        unsafe { view.data(rstring.as_slice()) }
+            .format("C")
+            .map_err(|e| e.into_error(&ruby))?
+            .shape([height, width, 3]);
+
+        Ok(())
+    }
+
+    fn is_available(_obj: Value) -> bool {
+        true
+    }
+}
+
+fn decode(ruby: &Ruby, arguments: &[Value]) -> Result<Value> {
+    let args = scan_args::<(String,), (), (), (), _, ()>(arguments)?;
+    let (width, height, punch) = get_kwargs::<_, (u32, u32, f64), (), ()>(
+        args.keywords,
+        &["width", "height", "punch"],
+        &[],
+    )?
+    .required;
+    let blurhash = args.required.0;
+
+    let decoded = blurhash_core::gpu::decode_gpu(&blurhash, width, height, punch)?;
+
+    let rstring = ruby.str_from_slice(decoded.as_slice());
+    let module: RModule = ruby.class_object().const_get("RuBlurHash")?;
+    let img_class: RClass = module.const_get("ImageString")?;
+    let instance = img_class.funcall("__send__", ("new", rstring))?;
+    ImageString::init(ruby, instance, width, height)?;
+
+    Ok(instance)
+}
+
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<()> {
+    let module = ruby.define_module("RuBlurHash")?;
+    module.define_module_function("encode", function!(encode, -1))?;
+    module.define_module_function("decode", function!(decode, -1))?;
+
+    let image_string = module.define_class("ImageString", ruby.class_string())?;
+    let _: Value = image_string
+        .singleton_class()?
+        .funcall("private", ("new",))?;
+    image_string.define_attr("width", Attr::Read)?;
+    image_string.define_attr("height", Attr::Read)?;
+    register::<ImageString>(image_string)?;
+
+    Ok(())
+}

data/rublurhash.gemspec

@@ -0,0 +1,28 @@
+require "json"
+
+rust_metadata = JSON.load(`cargo metadata --manifest-path=ext/Cargo.toml --no-deps --format-version=1`)
+
+Gem::Specification.new do |s|
+  s.name = "rublurhash"
+  s.version = rust_metadata["packages"][0]["version"]
+  s.authors = ["Kitaiti Makoto"]
+  s.licenses = "MIT"
+  s.summary = "Fast BlurHash implementation."
+  s.description = "Ruby binding for blurhash-core, a fast Rust implementation of BlurHash."
+  s.homepage = "https://gitlab.com/KitaitiMakoto/rublurhash"
+
+  s.files = Dir.chdir(__dir__) {`git ls-files -z`.split("\x0")}
+  s.extensions = ["ext/Cargo.toml"]
+  s.test_files = s.files.select {|file| file.start_with?("test/")}
+
+  s.add_development_dependency "rake"
+  s.add_development_dependency "kar"
+  s.add_development_dependency "test-unit"
+  s.add_development_dependency "test-unit-notify"
+  s.add_development_dependency "terminal-notifier" if RUBY_PLATFORM.match? /darwin/
+  s.add_development_dependency "rubygems-tasks"
+  s.add_development_dependency "steep"
+  s.add_development_dependency "ndav"
+  s.add_development_dependency "rdoc"
+  s.add_development_dependency "yard"
+end

data/sig/rublurhash.rbs

@@ -0,0 +1,14 @@
+module RuBlurHash
+  def self?.encode: (Object memory_view_producer, components_x: Integer, components_y: Integer) -> String
+                  | (Array[Integer] pixels, components_x: Integer, components_y: Integer, width: Integer, height: Integer) -> String
+                  | (String binary_data, components_x: Integer, components_y: Integer, width: Integer, height: Integer) -> String
+  def self?.decode: (String blur_hash_string, width: Integer, height: Integer, punch: Float) -> ImageString
+
+  # Binary string of image data
+  # 
+  # Also is a MemoryView producer
+  class ImageString < String
+    attr_reader width: Integer
+    attr_reader height: Integer
+  end
+end

data/sig/test/fiddle.rbs

@@ -0,0 +1,8 @@
+module Fiddle
+  class MemoryView
+    def self.export: (untyped) { (instance) -> untyped } -> untyped
+    def format: -> String
+    def shape: -> Array[Integer]
+    def []: (*Integer) -> Integer
+  end
+end

data/sig/test/rubygems.rbs

@@ -0,0 +1,10 @@
+module Gem
+  class Specification
+    def self.load: (String) -> instance
+    def full_name: -> String
+  end
+
+  class Platform
+    def self.local: -> instance
+  end
+end

data/sig/test/test-unit.rbs

@@ -0,0 +1,18 @@
+module Test
+  module Unit
+    class TestCase
+      include Assertions
+
+      def setup: -> void
+    end
+
+    module Assertions
+      def assert: (bool?) -> void
+                | { () -> void } -> void
+      def assert_match: (Regexp, String) -> void
+      def assert_equal: (untyped, untyped, ?_ToS) -> void
+      def assert_raise: { () -> void } -> void
+      def assert_path_exist: (path) -> void
+    end
+  end
+end

data/sig/test/test.rbs

@@ -0,0 +1,28 @@
+class TestRuBlurHash < Test::Unit::TestCase
+  include RuBlurHash
+
+  RE: Regexp
+  ENCODED: String
+
+  @img: Array[Integer]
+  @components_x: Integer
+  @components_y: Integer
+
+  def test_encode: -> void
+  def test_encode_memory_view: -> void
+  def test_decode: -> void
+  def test_image_string: -> void
+  def test_module_functions: -> void
+
+  private
+
+  def encoded_length: -> Integer
+end
+
+class TestPackage < Test::Unit::TestCase
+  @gemspec: Gem::Specification
+  @pkg_file: String
+
+  def test_build: -> void
+  def test_install: -> void
+end

data/test/helper.rb

@@ -0,0 +1,7 @@
+require "test/unit"
+require "test/unit/notify" if RUBY_PLATFORM.match? /darwin/
+require "fiddle"
+require "ndav"
+require "rublurhash"
+require "fileutils"
+require "tmpdir"

data/test/test_package.rb

@@ -0,0 +1,27 @@
+require_relative "helper"
+
+class TestPackage < Test::Unit::TestCase
+  def setup
+    @gemspec = Gem::Specification.load("rublurhash.gemspec")
+    @pkg_file = File.join("pkg", @gemspec.full_name + ".gem")
+    FileUtils.rmtree @pkg_file
+  end
+
+  def test_build
+    assert system("rake", "build")
+    assert File.size(@pkg_file) > 0
+  end
+
+  def test_install
+    system "rake", "build", exception: true
+    gem_file = File.join("pkg", @gemspec.full_name + ".gem")
+    Dir.mktmpdir do |dir|
+      dir = File.realpath(dir)
+      install_dir = File.join(dir, "install")
+      FileUtils.mkdir install_dir
+      system "gem", "install", "--install-dir", install_dir, "--no-document", gem_file, exception: true
+
+      assert_path_exist File.join(install_dir, "extensions", Gem::Platform.local.to_s, RbConfig::CONFIG["ruby_version"], @gemspec.full_name, "rublurhash.#{RbConfig::CONFIG['DLEXT']}")
+    end
+  end
+end

data/test/test_rublurhash.rb

@@ -0,0 +1,96 @@
+require_relative "helper"
+
+class TestRuBlurHash < Test::Unit::TestCase
+  include RuBlurHash
+
+  RE = /\A[0-~]+\z/
+  ENCODED = "LEHV6nWB2yk8pyo0adR*.7kCMdnj"
+
+  def setup
+    @img = [
+      [255, 0, 0],
+      [255, 0, 0],
+      [255, 0, 0],
+      [255, 0, 0]
+    ].flatten
+    @components_x = 4
+    @components_y = 3
+  end
+
+  def test_encode
+    encoded = encode(@img, width: 2, height: 2, components_x: @components_x, components_y: @components_y)
+
+    assert do
+      encoded.length == encoded_length
+    end
+    assert_match RE, encoded
+  end
+
+  def test_encode_memory_view
+    memview = NDAV.new(Fiddle::Pointer[@img.pack("C*")], shape: [2, 2, 3])
+    encoded = encode(memview, components_x: @components_x, components_y: @components_y)
+
+    assert do
+      encoded.length == encoded_length
+    end
+    assert_match RE, encoded
+    assert do
+      encode(@img, width: 2, height: 2, components_x: @components_x, components_y: @components_y) == encoded
+    end
+  end
+
+  def test_decode
+    decoded = decode(ENCODED, width: 32, height: 32, punch: 1.0)
+
+    assert do
+      decoded.bytesize == 32 * 32 * 3
+    end
+
+    img = decoded.unpack("CCC*")
+    img.each do |pixel|
+      assert do
+        pixel > 0
+      end
+    end
+
+    assert_equal 32, decoded.width
+    assert_equal 32, decoded.height
+
+    Fiddle::MemoryView.export decoded do |view|
+      assert_equal "C", view.format
+      assert_equal [32, 32, 3], view.shape
+      view.shape[0].times do |i|
+        view.shape[1].times do |j|
+          view.shape[2].times do |k|
+            assert_equal img[i * 96 + j * 3 + k], view[i, j, k], {i:, j:, k:}
+          end
+        end
+      end
+    end
+
+    assert_raise do
+      decode("!EHVWB2yk8pyo0adR*.7kCMdnj", width: 32, height: 32, punch: 1.0)
+    end
+
+    assert_raise do
+      decode("LEHV6nWB", width: 8, height: 8, punch: 1.0)
+    end
+  end
+
+  def test_image_string
+    assert_raise do
+      ImageString.new("123")
+    end
+  end
+
+  def test_module_functions
+    assert_equal encode(@img, width: 2, height: 2, components_x: @components_x, components_y: @components_y), RuBlurHash.encode(@img, width: 2, height: 2, components_x: @components_x, components_y: @components_y)
+    assert_equal decode(ENCODED, width: 32, height: 32, punch: 1.0), ::RuBlurHash.decode(ENCODED, width: 32, height: 32, punch: 1.0)
+  end
+
+  private
+
+  def encoded_length
+    4 + 2 * @components_x * @components_y
+  end
+end