image_util 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 27dbed58dd9646ef50f6ae022f3d2599629670f0d430f61c76416cb28d49bbd6
-  data.tar.gz: 55d78376ffbbf3f85b60db158ca65c46b96164c9e6c52b0d7324b70e1bd11dc4
+  metadata.gz: 31687d0660e040e340b6ed26f581f95de0746e33f992acf7dfcdb4fa4a88f4cd
+  data.tar.gz: 4fee3793295fb2207a54caa1ed430bdc43ddc8307f96ef597ba0ed777618b8e6
 SHA512:
-  metadata.gz: 2c14b302a030e83cc6f398f8560138c31f53e93d9059c7f2b18ce5b81aeb41e4922932a64e8221b5e2e52fc4e5c876ac4dfd74f0eb7630e907e5a74a50a52335
-  data.tar.gz: 6f3834f813239cc80418d54a01224ae5afbd28870a8beff19f1a2c32fabfe7a800d2cc59a857d98faed713c49fff2cc0519332927004c900a72709b08162bcc3
+  metadata.gz: c02064cb968adae5e5d5b5328922e77fd542d6ca4322a9259d27b513339ff44ca71e272f8cf01055d864f3dbc3fef702d3187a745e98af09a95f2dc9907470c4
+  data.tar.gz: 97c9852b31aab0d2b71f19579968d856fd87eed7339c3b2ec9e6bd1dcee3b674862821f6d4a033148db8d45b0a8228d890670d43c2f0ba921dc98d7d5ed774de

data/AGENTS.md

@@ -6,11 +6,10 @@
 - 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.
+- After adding new features or modifying existing ones, change documentation accordingly (especially README and especially CHANGELOG).
+- Don't discuss codec internals or bug fixes in README. Only list supported formats. Document bug fixes in the CHANGELOG, not in README.
 - Specs target at least 80% coverage as enforced by SimpleCov.
 - The library aims to remain lightweight and portable.
+- Remember to always ensure rake tests pass and Rubocop doesn't complain.
+- If you are an OpenAI Codex, don't upload images! Tell me to use `rebuild-images-in-readme` script.
+- When adding files into collection directories (like codec/), if something isn't part of a collection (ie. isn't a codec, but is a mixin), ensure to name the file like `_something.rb`. Consult existing directory structure.

data/CHANGELOG.md

@@ -1,5 +1,44 @@
-## [Unreleased]
-### Added
+## [0.3.0] - 2025-07-25
+- Rename `dither!` to `palette_reduce!`
+- Rename `#set_each_pixel_by_location` to `#set_each_pixel_by_location!` since it's mutable
+- Rename `color_length` to a more appropriate name `channels`
+- Thor based CLI with a `support` command that lists codec support, default
+  format handlers and detected terminal features
+- Replace `palette_reduce!` implementation with a much faster one
+- Terminal detection for graphic protocols
+- Support Kitty graphics protocol
+- Transform filter with rotate and flip operations
+- Fallback PNG codec via chunky_png
+- ImageMagick codec can now read and write `gif` and `apng` including animations
+- Redimension filter to change image dimensions
+- Sixel and Kitty codecs accept 1D images
+- `Pam.encode` no longer accepts `fill_to`; Sixel codecs pad images using the
+  redimension filter
+- Add `BitmapFont` with a sample hand crafted font, add `bitmap_text` generator.
+- `Color#*` can now accept another `Color` to multiply channels
+- Add `Colors` filter with `color_multiply!` and alias `*`
+- `bitmap_text` accepts multiline strings and supports colorization
+- `bitmap_text` supports left, center and right alignment
+- Add `BitmapText` filter for overlaying text onto images
+- `bitmap_text` filter now always respects an alpha channel when pasting text
+- Open ImageMagick codec pipes in binary mode for Windows compatibility
+- Format inference from file extension in `Image#to_file`
+- ImageMagick codec now reads PAM frames using the Pam codec
+- Force 8-bit output when decoding through ImageMagick to avoid 1-bit images on Windows
+- ImageMagick codec checks available formats before advertising APNG support
+- Add `Example` generator: `Image.example_rose`
+- Disable APNG on Windows until we find out something else than ImageMagick to support it
+
+## [0.2.0] - 2025-07-21
+- Ruby Sixel encoder now sets pixel aspect ratio metadata to display correctly in Windows Terminal
+- Support for all CSS color names
+- Range assignments with images now resize the image before pasting
+- Circle drawing filter
+- ImageMagick codec can encode and decode `png`, `jpeg` and `sixel`
+
+## [0.1.0] - 2025-07-21
+
+- Initial release
 - Drop support for Ruby 3.1
 - Native SIXEL encoder
 - Background filter
@@ -12,7 +51,3 @@
 - 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/README.md

@@ -1,144 +1,288 @@
 # 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.
+ImageUtil is a lightweight Ruby library focused on manipulating images directly in memory. Its primary goal is to help scripts visualize data right in the terminal by supporting SIXEL output alongside common image formats. The API is still evolving and should be considered unstable until version 1.0.
 
-Features include:
+## Creating an Image
 
-* 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.
+```ruby
+require 'image_util'
+
+# 40×40 RGBA image
+img = ImageUtil::Image.new(40, 40)
+```
+
+An optional block receives pixel coordinates and should return something that can be converted to a color. Dimensions of more than two axes are supported.
+
+```ruby
+img = ImageUtil::Image.new(128, 128) { |x, y| ImageUtil::Color[x, y, 40] }
+```
+
+![Constructor example](docs/samples/constructor.png)
+
+## Loading and Saving
 
-## Installation
+Instead of building an image from scratch you can load one with
+`ImageUtil::Image.from_string` or `ImageUtil::Image.from_file`.
+Both helpers understand the built in codecs for `png`, `jpeg`, `pam`, `gif`
+and `apng` formats:
 
-ImageUtil is available on RubyGems:
+```ruby
+img = ImageUtil::Image.from_file("logo.png")
+data = ImageUtil::Image.from_string(File.binread("logo.jpeg"))
+```
+
+A `from_file` method also supports passing IO objects:
 
-```bash
-gem install image_util
+```ruby
+img = ImageUtil::Image.from_file(IO.popen("magick rose: png:"))
+img.draw_line([0,0], [69,45], :blue)
 ```
 
-Alternatively add it to your `Gemfile`:
+![Pipe load example](docs/samples/pipe.png)
+
+The same formats can be written back using `to_string` or `to_file`.
+When saving to a file path, `to_file` can infer the format from the file extension.
 
 ```ruby
-gem "image_util"
+img.to_file("out.png")
+binary = img.to_string(:jpeg)
 ```
 
-Run `bundle install` afterwards.
+## Image Information
 
-You can also build and install the gem manually:
+After loading or creating an image, you can access information about it, like
+dimensions or color bits.
 
-```bash
-git clone https://github.com/rbutils/image_util.git
-cd image_util
-bundle exec rake install
+```ruby
+img.dimensions # => [20,30]
+img.width # => 20
+img.height # => 30
+img.color_bits # => 8 (means every channel has 8 bits of color)
+img.channels # => 3 (RGB)
 ```
 
-## Usage
+## Terminal Output
+
+Images can be previewed in compatible terminals:
 
 ```ruby
-require 'image_util'
+puts ImageUtil::Terminal.output_image($stdin, $stdout, img)
+```
+
+In `irb` or `pry` the `inspect` method shows the image automatically, so you can
+just evaluate the object:
 
-# create a 4×4 image using 8‑bit RGBA colors
-i = ImageUtil::Image.new(4, 4)
+```ruby
+img
+```
+
+The library checks if the Kitty graphics protocol is available and falls back to SIXEL otherwise. Kitty graphics protocol is supported by Kitty, Konsole
+and a couple others. SIXEL, most notably, works in Windows Terminal, Konsole (KDE), iTerm2 (macOS), XTerm (launch with: `xterm -ti vt340`). Here's how SIXEL
+looks in Konsole:
+
+![Sixel example](docs/samples/sixel.png)
+
+This library supports generating Sixel with either `libsixel`, `ImageMagick` or using a pure-Ruby Sixel generator. For best performance, try to install one of
+the earlier system packages. Both Kitty and SIXEL outputs also accept one-dimensional images, treating them as height `1`.
+
+
+## Color Values
+
+`ImageUtil::Color.from` (also known as `ImageUtil::Color.[]`) accepts several inputs:
+
+- Another `Color` instance
+- Arrays of numeric components (`[r, g, b]` or `[r, g, b, a]`)
+- Numbers (used for all RGB channels)
+- Symbols or strings containing CSS color names (`:rebeccapurple`, 'papayawhip')
+- Hex strings like `'#abc'`, `'#aabbcc'` or `'#rrggbbaa'`
+
+When numeric components are given, integers are first clamped to the `0..255`
+range. Float values are treated as fractions of 255, so `0.5` becomes `127.5`
+and `1.0` becomes `255`. After scaling, values are again clamped to this range.
+If the alpha channel is omitted it defaults to `255`.
+
+```ruby
+ImageUtil::Color[0.5] # => #808080
+ImageUtil::Color[:red] # => #ff0000
+ImageUtil::Color["#fc0"] # => #ffcc00
+```
+
+Note that whenever the library expects a color, it may be given in any form accepted by this function.
+
+## Pixel Access
+
+Pixels can be accessed with integer coordinates or ranges. When ranges are used
+a new `Image` containing that region is returned and can be modified separately.
+
+```ruby
+img[0, 0] = '#ff0000'
+patch = img[0..1, 0..1]
+```
 
-# set the top‑left pixel to red
-i[0, 0] = ImageUtil::Color[255, 0, 0]
+For instance, you can extract a region, edit it and paste it back:
 
-# display the image in a SIXEL-capable terminal
-puts i.to_sixel
+```ruby
+img = ImageUtil::Image.new(128, 128) { [0, 0, 0] }
+corner = img[0..32, 0..32]
+corner.all = :green
+img[0..32, 0..32] = corner
+img[2, 2] = :yellow
+# img.to_file("pixel_patch.png", :png)
+img
 ```
 
-Images can also be iterated over or modified using ranges:
+![Range access example](docs/samples/range.png)
+
+Assigning an image to a range automatically resizes it to fit before pasting.
+
+On the other hand, if you assign a color to a range, it will fill all referenced
+pixels with that color (draw a rectangle).
+
+Iteration helpers operate on arbitrary ranges and share the same syntax used
+when indexing images.  `each_pixel` yields color objects, while
+`each_pixel_location` yields coordinate arrays.  `set_each_pixel_by_location!`
+assigns the value returned by the block to every location (unless `nil` is returned).
 
 ```ruby
-# fill an area with blue
-i[0..1, 0..1] = ImageUtil::Color['#0000ff']
+# create an all-black image
+img = ImageUtil::Image.new(128, 128) { :black }
 
-# iterate over every pixel
-i.each_pixel do |pixel|
-  # pixel is an ImageUtil::Color instance
+# fill a checkerboard pattern
+img.set_each_pixel_by_location! do |x, y|
+  :red if (x + y).odd?
 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)
+# count how many red pixels were set
+black = img.each_pixel.count { |c| c == :red }
 
-# draw a diagonal line
-i.draw_line!([0, 0], [3, 3], ImageUtil::Color['red'], view: ImageUtil::View::Rounded)
+# display img in terminal
+img
 ```
 
-`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.
+![Iterator example](docs/samples/iterator.png)
+
+Note that instead of manually calling `set_each_pixel_by_location`, you can just pass a block to `ImageUtil::Image.new`.
 
-### Reading and Writing Images
+## Filters
+
+`ImageUtil::Image` ships with a few convenience filters. Each bang method
+modifies the image in place while the non-bang version returns a copy.
+
+### Background
+
+Flatten an RGBA image on a solid color.
 
 ```ruby
-# detect format automatically when loading from a file
-img = ImageUtil::Image.from_file("photo.png")
+# create a transparent image gradient containing shades of red only
+img = ImageUtil::Image.new(128, 128) { |x, y| [255, 0, 0, x + y] }
+
+# put it on a blue background
+img.background([0, 0, 255])
+```
 
-# save using a specific codec
-img.to_file("out.jpg", :jpeg)
+![Background example](docs/samples/background.png)
 
-# convert directly to a string
-data = img.to_string(:png)
+### Paste
+
+Place one image over another. When `respect_alpha` is true, the pasted pixels are
+blended with the base image.
+
+```ruby
+base    = ImageUtil::Image.new(128, 128) { |x, y| [x, y, 50] }
+overlay = ImageUtil::Image.new(64, 64)  { |x, y| [255, 0, 0, (x + y) * 2] }
+base.paste!(overlay, 32, 32, respect_alpha: true)
 ```
 
-### Filters
+![Paste example](docs/samples/paste.png)
+
+### Draw
+
+Draw simple shapes directly on the image.
 
 ```ruby
-# reduce palette to 32 colors
-dithered = img.dither(32)
+img = ImageUtil::Image.new(128, 128) { [0, 0, 0] }
+img.draw_line!([0, 0], [127, 127], :red)
+img.draw_line!([0, 127], [127, 0], :lime)
+img.draw_circle!([64, 64], 30, :blue)
+```
+
+![Draw example](docs/samples/draw.png)
+
+### Resize
 
-# composite two images without altering the originals
-result = base.paste(other, 10, 10)
+Scale an image to new dimensions.
 
-# apply a background color to an RGBA image
-flattened = img.background(ImageUtil::Color[255, 255, 255])
+```ruby
+img = ImageUtil::Image.new(128, 128) { |x, y| [x, y, 30] }
+img[20, 20] = img.resize(64, 64)
+img
 ```
 
-### Working with Views
+![Resize example](docs/samples/resize.png)
+
+### Palette
+
+Reduce the image to a limited palette.
 
 ```ruby
-# access using fractional coordinates
-interp = img.view(ImageUtil::View::Interpolated)
-interp[1.2, 2.8] = ImageUtil::Color[0, 0, 255]
+img = ImageUtil::Image.new(128, 128) { |x, y| [x * 2, y * 2, 200] }
+img.palette_reduce(64)
+```
+
+![Palette reduce example](docs/samples/pdither.png)
+
+### Transform
+
+Rotate or flip an image.
 
-# round coordinates instead
-rounded = img.view(ImageUtil::View::Rounded)
-color = rounded[1.6, 0.3]
+```ruby
+img = ImageUtil::Image.new(128, 128) { |x, y| [x, y, 0] }
+img.flip!(:x)
+img.rotate!(90)
+# img.rotate!(90, axes: [:x, :z])
 ```
 
-### Codecs
+![Transform example](docs/samples/transform.png)
+
+### Colors
 
-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.
+Multiply all pixels by a color.
 
 ```ruby
-png = ImageUtil::Codec.encode(:png, i)
-back = ImageUtil::Codec.decode(:png, png)
+img = ImageUtil::Image.new(128, 128) { [255, 255, 255, 128] }
+img * :red
+```
 
-File.open("img.pam", "wb") do |f|
-  ImageUtil::Codec.encode_io(:pam, i, f)
-end
+![Colors example](docs/samples/colors.png)
+
+### Bitmap Text
+
+Overlay text using the bundled bitmap font.
+
+```ruby
+img = ImageUtil::Image.new(128, 128) { [0, 0, 0] }
+img.bitmap_text!("Lorem ipsum dolor sit\namet, consectetur adipiscing\nelit.", 2, 2, color: :blue)
 ```
 
-You can read images from files without specifying the format:
+![Bitmap text example](docs/samples/bitmap_text.png)
+
+### Redimension
+
+Change how many dimensions an image has or adjust their size.
 
 ```ruby
-image = ImageUtil::Image.from_file("picture.jpg")
+img = ImageUtil::Image.new(64, 64) { :white }
+img.redimension!(128, 128) # can also add additional dimensions
+img.background(:blue)
 ```
 
-Use `ImageUtil::Codec.supported?(format)` to check if a particular format is
-available. Unsupported formats raise `ImageUtil::Codec::UnsupportedFormatError`.
+![Redimension example](docs/samples/redimension.png)
+
+## Command Line
+
+The gem includes a small `image_util` CLI. Run `image_util support` to list
+available codecs, default format handlers and detected terminal features.
+See [docs/cli.md](docs/cli.md) for details.
 
 ## Development
 
@@ -146,6 +290,10 @@ 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.
 
+### Benchmarking
+
+Run `bin/benchmark` to execute a small benchmark.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at

data/Rakefile

@@ -8,3 +8,8 @@ RSpec::Core::RakeTask.new(:spec)
 RuboCop::RakeTask.new
 
 task default: %i[spec rubocop]
+
+desc "Run benchmarks"
+task :bench do
+  ruby File.expand_path("bin/benchmark", __dir__)
+end

data/docs/cli.md

@@ -0,0 +1,5 @@
+# Command Line Interface
+
+Run `image_util support` to see which codecs are available on your system,
+which codec handles each format by default, and which terminal features are
+detected.

data/exe/image_util

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "image_util"
+
+ImageUtil::CLI.start(ARGV)

data/lib/image_util/benchmarking.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "benchmark/ips"
+
+module ImageUtil
+  module Benchmarking
+    module_function
+
+    # Benchmarks creating a 64×64×64 black image for the given time in seconds.
+    def image_creation(seconds = 5)
+      ::Benchmark.ips do |x|
+        x.warmup = 0
+        x.time = seconds
+        x.report("from Symbol") { Image.new(64, 64, 64) { :black } }
+        x.report("from Array (4->4 channels)") { Image.new(64, 64, 64) { |x,y,z| [x,y,z,255] } }
+        x.report("from Array (3->4 channels)") { Image.new(64, 64, 64) { |x,y,z| [x,y,z] } }
+        x.report("from Array (3->3 channels)") { Image.new(64, 64, 64, channels: 3) { |x,y,z| [x,y,z] } }
+      end
+    end
+
+    def run(seconds = 5)
+      image_creation(seconds)
+    end
+  end
+end

data/lib/image_util/bitmap_font/fonts/smfont/charset.txt

@@ -0,0 +1 @@
+abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789`~!@#$%^&*()-_+=:;'"|\/?.,[]{}<>€ 

data/lib/image_util/bitmap_font.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module ImageUtil
+  class BitmapFont
+    def initialize(name)
+      font = Image.from_file("#{__dir__}/bitmap_font/fonts/#{name}/font.png")
+      charset = File.read("#{__dir__}/bitmap_font/fonts/#{name}/charset.txt").chomp.chars
+
+      parse_image(font, charset)
+    end
+
+    def parse_image(font, charset)
+      font.height.times do |n|
+        if font[0,n] == :red
+          @height = n
+          break
+        end
+      end
+
+      character_pos = []
+
+      n = 0
+      while n < font.width
+        if font[n, @height] == :blue
+          start = n
+          n += 1 while n < font.width && font[n, @height] == :blue
+          n -= 1
+          finish = n
+          character_pos << (start..finish)
+        end
+        n += 1
+      end
+
+      font = font.dup
+      font.set_each_pixel_by_location! do |x,y|
+        [255, 255, 255, 255 - font[x,y].g]
+      end
+
+      @characters = character_pos.map.with_index do |range,idx|
+        [charset[idx], font[range, ...@height]]
+      end.to_h
+    end
+
+    def render_line_of_text(text)
+      width = 1
+      text.chars.each do |char|
+        width += @characters[char].width + 1
+      end
+      width -= 1
+
+      img = Image.new(width, @height)
+      width = 0
+      text.chars.each do |char|
+        img[width,0] = @characters[char]
+        width += @characters[char].width + 1
+      end
+
+      img
+    end
+
+    def self.fonts
+      Dir["#{__dir__}/bitmap_font/fonts/*"].map { |i| File.basename(i) }
+    end
+
+    def self.default_font = "smfont"
+
+    def self.cached_load(font)
+      @fonts ||= {}
+      @fonts[font] ||= BitmapFont.new(font)
+    end
+  end
+end