image_util 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 27dbed58dd9646ef50f6ae022f3d2599629670f0d430f61c76416cb28d49bbd6
+  data.tar.gz: 55d78376ffbbf3f85b60db158ca65c46b96164c9e6c52b0d7324b70e1bd11dc4
+SHA512:
+  metadata.gz: 2c14b302a030e83cc6f398f8560138c31f53e93d9059c7f2b18ce5b81aeb41e4922932a64e8221b5e2e52fc4e5c876ac4dfd74f0eb7630e907e5a74a50a52335
+  data.tar.gz: 6f3834f813239cc80418d54a01224ae5afbd28870a8beff19f1a2c32fabfe7a800d2cc59a857d98faed713c49fff2cc0519332927004c900a72709b08162bcc3

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,96 @@
+AllCops:
+  TargetRubyVersion: 3.2
+  NewCops: disable
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+  Exclude:
+    - 'spec/**/*'
+    - 'image_util.gemspec'
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Layout/LineLength:
+  Max: 170
+
+Metrics/BlockLength:
+  Enabled: false
+Metrics/ClassLength:
+  Enabled: false
+Metrics/MethodLength:
+  Enabled: false
+Metrics/AbcSize:
+  Enabled: false
+Metrics/CyclomaticComplexity:
+  Enabled: false
+Metrics/PerceivedComplexity:
+  Enabled: false
+
+Naming/MethodParameterName:
+  Enabled: false
+
+Lint/SuppressedException:
+  Enabled: false
+
+Style/MultilineBlockChain:
+  Enabled: false
+
+Style/PerlBackrefs:
+  Enabled: false
+
+Style/FormatStringToken:
+  Enabled: false
+Style/FormatString:
+  Enabled: false
+
+Layout/SpaceAfterComma:
+  Enabled: false
+Layout/SpaceAroundOperators:
+  Enabled: false
+Layout/TrailingWhitespace:
+  Enabled: false
+
+Style/IfUnlessModifier:
+  Enabled: false
+Style/NilComparison:
+  Enabled: false
+Style/NumericPredicate:
+  Enabled: false
+
+Lint/DuplicateMethods:
+  Enabled: false
+
+Lint/Void:
+  Enabled: false
+
+Layout/SpaceBeforeBlockBraces:
+  Enabled: false
+
+Lint/UnusedBlockArgument:
+  Enabled: false
+
+Naming/AccessorMethodName:
+  Enabled: false
+
+Style/SingleLineMethods:
+  Enabled: false
+
+Layout/EmptyLineAfterGuardClause:
+  Enabled: false
+
+Style/IfInsideElse:
+  Enabled: false
+
+Style/RedundantBegin:
+  Enabled: false
+
+Style/SymbolProc:
+  Enabled: false
+

data/AGENTS.md

@@ -0,0 +1,16 @@
+# Contributor Guidelines
+
+- Specs mirror file structure under `lib`. For example, `lib/image_util/image/buffer.rb` has a spec at `spec/image/buffer_spec.rb`.
+- Use `autoload` for loading internal files. Avoid `require` and `require_relative`.
+- Start every Ruby file with `# frozen_string_literal: true`.
+- Prefer double-quoted strings except in specs and the gemspec.
+- Use RSpec's `should` syntax instead of `expect`.
+- For one-line methods, use the `def name = expression` style.
+
+Additional notes from the existing code:
+- Image data is stored in `Image::Buffer` backed by `IO::Buffer`.
+- Use `Filter::Mixin#define_immutable_version` to add non-bang versions of mutating filters.
+- Views such as `View::Interpolated` and `View::Rounded` are built with `Data.define`.
+- Pure Ruby algorithms are provided with optional FFI wrappers for libpng, libturbojpeg and libsixel.
+- Specs target at least 80% coverage as enforced by SimpleCov.
+- The library aims to remain lightweight and portable.

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+## [Unreleased]
+### Added
+- Drop support for Ruby 3.1
+- Native SIXEL encoder
+- Background filter
+- Format auto-detection using magic numbers
+- Faster 1D paste using direct buffer copy
+- Libsixel encoder with default palette
+- JPEG support via libturbojpeg
+- PNG support via libpng
+- Dither filter for palette reduction
+- Paste and Draw filters for compositing and drawing
+- Rounded and interpolated pixel views
+- `Image#view` helper for custom access
+
+## [0.1.0] - 2025-07-19
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 hmdne
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,157 @@
+# ImageUtil
+
+ImageUtil provides a minimal in-memory image container and a set of utilities for handling raw pixel data in Ruby. It is aimed at small scripts and tools that need to manipulate images without relying on heavy external dependencies.
+
+Features include:
+
+* Representation of images with arbitrary dimensions.
+* Support for 8, 16 or 32 bit components and RGB or RGBA color values.
+* A `Color` helper class capable of parsing numbers, arrays and HTML style strings.
+* Conversion of an image to PAM or SIXEL for quick previews in compatible terminals.
+* Built-in SIXEL encoder that works without ImageMagick.
+* Convenience methods for iterating over pixel locations and setting values.
+* Overlaying colors with the `+` operator which blends using the alpha channel.
+* Automatic format detection when reading images from strings or files.
+* Alternate pixel views for interpolated or rounded coordinates.
+
+## Installation
+
+ImageUtil is available on RubyGems:
+
+```bash
+gem install image_util
+```
+
+Alternatively add it to your `Gemfile`:
+
+```ruby
+gem "image_util"
+```
+
+Run `bundle install` afterwards.
+
+You can also build and install the gem manually:
+
+```bash
+git clone https://github.com/rbutils/image_util.git
+cd image_util
+bundle exec rake install
+```
+
+## Usage
+
+```ruby
+require 'image_util'
+
+# create a 4×4 image using 8‑bit RGBA colors
+i = ImageUtil::Image.new(4, 4)
+
+# set the top‑left pixel to red
+i[0, 0] = ImageUtil::Color[255, 0, 0]
+
+# display the image in a SIXEL-capable terminal
+puts i.to_sixel
+```
+
+Images can also be iterated over or modified using ranges:
+
+```ruby
+# fill an area with blue
+i[0..1, 0..1] = ImageUtil::Color['#0000ff']
+
+# iterate over every pixel
+i.each_pixel do |pixel|
+  # pixel is an ImageUtil::Color instance
+end
+
+# paste one image into another
+target = ImageUtil::Image.new(8, 8) { ImageUtil::Color[0] }
+source = ImageUtil::Image.new(2, 2) { ImageUtil::Color[255, 0, 0, 128] }
+target.paste!(source, 3, 3, respect_alpha: true)
+
+# draw a diagonal line
+i.draw_line!([0, 0], [3, 3], ImageUtil::Color['red'], view: ImageUtil::View::Rounded)
+```
+
+`View::Interpolated` provides subpixel access while `View::Rounded` snaps
+coordinates to the nearest pixel. These views are useful for drawing
+operations like the example above.
+
+### Reading and Writing Images
+
+```ruby
+# detect format automatically when loading from a file
+img = ImageUtil::Image.from_file("photo.png")
+
+# save using a specific codec
+img.to_file("out.jpg", :jpeg)
+
+# convert directly to a string
+data = img.to_string(:png)
+```
+
+### Filters
+
+```ruby
+# reduce palette to 32 colors
+dithered = img.dither(32)
+
+# composite two images without altering the originals
+result = base.paste(other, 10, 10)
+
+# apply a background color to an RGBA image
+flattened = img.background(ImageUtil::Color[255, 255, 255])
+```
+
+### Working with Views
+
+```ruby
+# access using fractional coordinates
+interp = img.view(ImageUtil::View::Interpolated)
+interp[1.2, 2.8] = ImageUtil::Color[0, 0, 255]
+
+# round coordinates instead
+rounded = img.view(ImageUtil::View::Rounded)
+color = rounded[1.6, 0.3]
+```
+
+### Codecs
+
+ImageUtil includes a small registry of codecs for converting images to and from
+common formats such as PNG, JPEG and SIXEL. The library ships with pure Ruby
+encoders and FFI wrappers around `libpng`, `libturbojpeg` and `libsixel` when
+available.
+
+```ruby
+png = ImageUtil::Codec.encode(:png, i)
+back = ImageUtil::Codec.decode(:png, png)
+
+File.open("img.pam", "wb") do |f|
+  ImageUtil::Codec.encode_io(:pam, i, f)
+end
+```
+
+You can read images from files without specifying the format:
+
+```ruby
+image = ImageUtil::Image.from_file("picture.jpg")
+```
+
+Use `ImageUtil::Codec.supported?(format)` to check if a particular format is
+available. Unsupported formats raise `ImageUtil::Codec::UnsupportedFormatError`.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then run
+`rake spec` to execute the tests. You can also run `bin/console` for an
+interactive prompt for experimenting with the library.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+<https://github.com/rbutils/image_util>.
+
+## License
+
+The gem is available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/image_util/codec/_guard.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module ImageUtil
+  module Codec
+    module Guard
+      def guard_supported_format!(format, supported)
+        return if supported.map { |f| f.to_s.downcase.to_sym }.include?(format.to_s.downcase.to_sym)
+
+        raise UnsupportedFormatError, "unsupported format #{format}"
+      end
+
+      def guard_image_class!(image)
+        return if image.is_a?(Image)
+
+        raise ArgumentError, "image must be an ImageUtil::Image"
+      end
+
+      def guard_2d_image!(image)
+        guard_image_class!(image)
+        return if image.dimensions.length == 2
+
+        raise ArgumentError, "only 2D images supported"
+      end
+
+      def guard_8bit_colors!(image)
+        guard_image_class!(image)
+        return if image.color_bits == 8
+
+        raise ArgumentError, "only 8-bit colors supported"
+      end
+
+      module_function :guard_supported_format!, :guard_image_class!, :guard_2d_image!, :guard_8bit_colors!
+    end
+  end
+end

data/lib/image_util/codec/image_magick.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module ImageUtil
+  module Codec
+    module ImageMagick
+      SUPPORTED_FORMATS = [:sixel].freeze
+
+      extend Guard
+
+      module_function
+
+      def magick_available?
+        return @magick_available unless @magick_available.nil?
+
+        @magick_available = system("magick", "-version", out: File::NULL, err: File::NULL)
+      end
+
+      def supported?(format = nil)
+        return false unless magick_available?
+
+        return true if format.nil?
+
+        SUPPORTED_FORMATS.include?(format.to_s.downcase.to_sym)
+      end
+
+      def encode(format, image)
+        guard_supported_format!(format, SUPPORTED_FORMATS)
+
+        IO.popen("magick pam:- sixel:-", "r+") do |io|
+          io << Codec::Pam.encode(:pam, image, fill_to: 6)
+          io.close_write
+          io.read
+        end
+      end
+
+      def encode_io(format, image, io)
+        io << encode(format, image)
+      end
+
+      def decode(*)
+        raise UnsupportedFormatError, "decode not supported for sixel"
+      end
+
+      def decode_io(*)
+        raise UnsupportedFormatError, "decode not supported for sixel"
+      end
+    end
+  end
+end

data/lib/image_util/codec/libpng.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module ImageUtil
+  module Codec
+    module Libpng
+      SUPPORTED_FORMATS = [:png].freeze
+
+      extend Guard
+
+      begin
+        require "ffi"
+
+        extend FFI::Library
+        ffi_lib [
+          "libpng16.so.16", # Linux
+          "libpng16-16.dll", "libpng16.dll", # Windows
+          "libpng16.16.dylib", "libpng16.dylib", # macOS
+          "libpng16.so", "libpng.so", "libpng.dll", "libpng.dylib", # generic
+          "libpng16", "libpng", "png16", "png"
+        ]
+
+        AVAILABLE = true
+      rescue LoadError
+        AVAILABLE = false
+      end
+
+      PNG_IMAGE_VERSION = 1
+
+      PNG_FORMAT_FLAG_ALPHA = 0x01
+      PNG_FORMAT_FLAG_COLOR = 0x02
+      PNG_FORMAT_FLAG_LINEAR = 0x04
+
+      PNG_FORMAT_RGB  = PNG_FORMAT_FLAG_COLOR
+      PNG_FORMAT_RGBA = PNG_FORMAT_FLAG_COLOR | PNG_FORMAT_FLAG_ALPHA
+
+      if AVAILABLE
+        class PngImage < FFI::Struct
+          layout :opaque, :pointer,
+                 :version, :uint32,
+                 :width, :uint32,
+                 :height, :uint32,
+                 :format, :uint32,
+                 :flags, :uint32,
+                 :colormap_entries, :uint32,
+                 :warning_or_error, :uint32,
+                 :message, [:char, 64]
+        end
+
+        attach_function :png_image_write_to_memory, %i[pointer pointer pointer int pointer int pointer], :int
+        attach_function :png_image_begin_read_from_memory, %i[pointer pointer size_t], :int
+        attach_function :png_image_finish_read, %i[pointer pointer pointer int pointer], :int
+        attach_function :png_image_free, [:pointer], :void
+      end
+
+      module_function
+
+      def supported?(format = nil)
+        return false unless AVAILABLE
+
+        return true if format.nil?
+
+        SUPPORTED_FORMATS.include?(format.to_s.downcase.to_sym)
+      end
+
+      def encode(format, image)
+        guard_supported_format!(format, SUPPORTED_FORMATS)
+        raise UnsupportedFormatError, "libpng not available" unless AVAILABLE
+
+        guard_2d_image!(image)
+        guard_8bit_colors!(image)
+
+        fmt = if image.color_length == 4
+                PNG_FORMAT_RGBA
+              else
+                PNG_FORMAT_RGB
+              end
+
+        img = PngImage.new
+        img[:version] = PNG_IMAGE_VERSION
+        img[:width] = image.width
+        img[:height] = image.height
+        img[:format] = fmt
+        img[:flags] = 0
+        img[:colormap_entries] = 0
+
+        row_stride = image.width * image.color_length
+        buffer_ptr = FFI::MemoryPointer.from_string(image.buffer.get_string)
+        size_ptr = FFI::MemoryPointer.new(:size_t)
+
+        ok = png_image_write_to_memory(img, nil, size_ptr, 0, buffer_ptr, row_stride, nil)
+        raise StandardError, img[:message].to_s if ok.zero?
+
+        size = size_ptr.read_ulong
+        out_ptr = FFI::MemoryPointer.new(:uchar, size)
+        ok = png_image_write_to_memory(img, out_ptr, size_ptr, 0, buffer_ptr, row_stride, nil)
+        raise StandardError, img[:message].to_s if ok.zero?
+
+        out_ptr.read_string(size_ptr.read_ulong)
+      ensure
+        png_image_free(img) if img
+      end
+
+      def encode_io(format, image, io)
+        io << encode(format, image)
+      end
+
+      def decode(format, data)
+        guard_supported_format!(format, SUPPORTED_FORMATS)
+        raise UnsupportedFormatError, "libpng not available" unless AVAILABLE
+
+        img = PngImage.new
+        img[:version] = PNG_IMAGE_VERSION
+
+        data_ptr = FFI::MemoryPointer.from_string(data)
+        ok = png_image_begin_read_from_memory(img, data_ptr, data.bytesize)
+        raise StandardError, img[:message].to_s if ok.zero?
+
+        img[:format] = PNG_FORMAT_RGBA
+        row_stride = img[:width] * 4
+        buffer_ptr = FFI::MemoryPointer.new(:uchar, row_stride * img[:height])
+
+        ok = png_image_finish_read(img, nil, buffer_ptr, row_stride, nil)
+        raise StandardError, img[:message].to_s if ok.zero?
+
+        raw = buffer_ptr.read_string(row_stride * img[:height])
+        io_buf = IO::Buffer.for(raw)
+        buf = Image::Buffer.new([img[:width], img[:height]], 8, 4, io_buf)
+        Image.from_buffer(buf)
+      ensure
+        png_image_free(img) if img
+      end
+
+      def decode_io(format, io)
+        decode(format, io.read)
+      end
+    end
+  end
+end

data/lib/image_util/codec/libsixel.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module ImageUtil
+  module Codec
+    module Libsixel
+      SUPPORTED_FORMATS = [:sixel].freeze
+
+      # https://github.com/libsixel/libsixel
+      SIXEL_PALETTE_MAX = 256
+      SIXEL_LARGE_AUTO = 0
+      SIXEL_REP_AUTO = 0
+      SIXEL_QUALITY_AUTO = 0
+      SIXEL_DIFFUSE_AUTO = 0
+      SIXEL_PIXELFORMAT_RGB888   = 3
+      SIXEL_PIXELFORMAT_RGBA8888 = 0x11
+
+      extend Guard
+
+      begin
+        require "ffi"
+
+        extend FFI::Library
+        ffi_lib [
+          "libsixel.so.1", # Linux
+          "libsixel-1.dll", "libsixel.dll", # Windows
+          "libsixel.1.dylib", "libsixel.dylib", # macOS
+          "libsixel.so", "libsixel"
+        ]
+
+        callback :write_function, %i[pointer int pointer], :int
+
+        attach_function :sixel_output_new, %i[pointer write_function pointer pointer], :int
+        attach_function :sixel_output_unref, [:pointer], :void
+        attach_function :sixel_dither_new, %i[pointer int pointer], :int
+        attach_function :sixel_dither_initialize, %i[pointer pointer int int int int int int], :int
+        attach_function :sixel_dither_set_diffusion_type, %i[pointer int], :void
+        attach_function :sixel_dither_unref, [:pointer], :void
+        attach_function :sixel_encode, %i[pointer int int int pointer pointer], :int
+
+        AVAILABLE = true
+      rescue LoadError
+        AVAILABLE = false
+      end
+
+      module_function
+
+      def supported?(format = nil)
+        return false unless AVAILABLE
+
+        return true if format.nil?
+
+        SUPPORTED_FORMATS.include?(format.to_s.downcase.to_sym)
+      end
+
+      def encode(format, image)
+        guard_supported_format!(format, SUPPORTED_FORMATS)
+        raise UnsupportedFormatError, "libsixel not available" unless AVAILABLE
+
+        guard_2d_image!(image)
+        guard_8bit_colors!(image)
+
+        fmt = image.color_length == 4 ? SIXEL_PIXELFORMAT_RGBA8888 : SIXEL_PIXELFORMAT_RGB888
+
+        data = "".b
+        writer = FFI::Function.new(:int, %i[pointer int pointer]) do |ptr, size, _|
+          data << ptr.read_string(size)
+          size
+        end
+
+        out_ptr = FFI::MemoryPointer.new(:pointer)
+        res = sixel_output_new(out_ptr, writer, nil, nil)
+        raise StandardError, "sixel_output_new failed" if res != 0
+
+        output = out_ptr.read_pointer
+
+        dither_ptr = FFI::MemoryPointer.new(:pointer)
+        res = sixel_dither_new(dither_ptr, -1, nil)
+        raise StandardError, "sixel_dither_new failed" if res != 0
+
+        dither = dither_ptr.read_pointer
+
+        pixels = image.buffer.get_string
+        buf_ptr = FFI::MemoryPointer.new(:uchar, pixels.bytesize)
+        buf_ptr.put_bytes(0, pixels)
+
+        res = sixel_dither_initialize(
+          dither,
+          buf_ptr,
+          image.width,
+          image.height,
+          fmt,
+          SIXEL_LARGE_AUTO,
+          SIXEL_REP_AUTO,
+          SIXEL_QUALITY_AUTO
+        )
+        raise StandardError, "sixel_dither_initialize failed" if res != 0
+
+        sixel_dither_set_diffusion_type(dither, SIXEL_DIFFUSE_AUTO)
+
+        res = sixel_encode(buf_ptr, image.width, image.height, fmt, dither, output)
+        raise StandardError, "sixel_encode failed" if res != 0
+
+        data
+      ensure
+        sixel_dither_unref(dither) if defined?(dither) && dither && !dither.null?
+        sixel_output_unref(output) if defined?(output) && output && !output.null?
+      end
+
+      def encode_io(format, image, io)
+        io << encode(format, image)
+      end
+
+      def decode(*)
+        raise UnsupportedFormatError, "decode not supported for sixel"
+      end
+
+      def decode_io(*)
+        raise UnsupportedFormatError, "decode not supported for sixel"
+      end
+    end
+  end
+end