image_util 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 92f9a0c088385d833ceee58b203a3ba52a4de3d2cbfdd16ed6dc8d0213e18753
-  data.tar.gz: 275a94eb28e30c8d1a59ba25723284e864e8ad9b8a1041826cba37d983ba01fd
+  metadata.gz: 893e648382567326c70c82a4b3e3b6580889229c9d56c7a20ec4d182b45332b4
+  data.tar.gz: 70fd8a63b0551a0aaca12dae391c076fb01621443ec1ae5e5f92c680655277f2
 SHA512:
-  metadata.gz: 523748193e1b51083729b1583cfec3ac19ec02a11e893cc3d858deb30388eebd013a01ade2770cd236c2f947bffc0cc2583783d3094552451d99b873d840311b
-  data.tar.gz: 228f82c3508d236822c4a6e27ad721381ffa42aaa31d1e3ab839eeaf9d60363ab2bcd7e6340fab00cdeac23320ad4681036187bd2eb5bb5680242ff9a8451464
+  metadata.gz: 89a0a3bf90307337674acae7e1315505bc4a8363e58c041388dc6e6beeaab3f03e4534d2ff41e9a97c23f5775e62db6ebe5493658ac2b81e06f3a650a197d28a
+  data.tar.gz: 6b425b6539c389431e78cdc98744a82888a3f55e0fdeed64062bf69a3e0448fec84e83264b3dd1380133a5adafa87e5751dd36595c7c3dc413e4ead3173d21ae

data/AGENTS.md

@@ -10,3 +10,6 @@
 - 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,3 +1,39 @@
+## [0.4.0] - 2025-10-04
+- BREAKING: Float color components now share the 0..255 range with integers instead of being scaled from 0..1.
+- Add `define_mutable_version` helper to create bang versions from immutable methods
+- Add `background!` and `resize!` filters
+
+## [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

data/README.md

@@ -14,34 +14,59 @@ 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(4, 4) { |x, y| ImageUtil::Color[x * 64, y * 64, 0] }
+img = ImageUtil::Image.new(128, 128) { |x, y| ImageUtil::Color[x, y, 40] }
 ```
 
+![Constructor example](docs/samples/constructor.png)
+
 ## Loading and Saving
 
 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` and `pam`
-formats:
+Both helpers understand the built in codecs for `png`, `jpeg`, `pam`, `gif`
+and `apng` formats:
 
 ```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:
+
+```ruby
+img = ImageUtil::Image.from_file(IO.popen("magick rose: png:"))
+img.draw_line([0,0], [69,45], :blue)
+```
+
+![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
-img.to_file("out.png", :png)
+img.to_file("out.png")
 binary = img.to_string(:jpeg)
 ```
 
-## SIXEL Output
+## Image Information
+
+After loading or creating an image, you can access information about it, like
+dimensions or color bits.
+
+```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)
+```
+
+## Terminal Output
 
 Images can be previewed in compatible terminals:
 
 ```ruby
-puts img.to_sixel
+puts ImageUtil::Terminal.output_image($stdin, $stdout, img)
 ```
 
 In `irb` or `pry` the `inspect` method shows the image automatically, so you can
@@ -51,12 +76,15 @@ just evaluate the object:
 img
 ```
 
-Most notably, SIXEL works in Windows Terminal, Konsole (KDE), iTerm2 (macOS), XTerm (launch with: `xterm -ti vt340`). Here's how it looks in Konsole:
+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`.
 
-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.
 
 ## Color Values
 
@@ -68,13 +96,13 @@ This library supports generating Sixel with either `libsixel`, `ImageMagick` or
 - 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`.
+When numeric components are given, values are clamped directly to the `0..255`
+range regardless of whether they are integers or floats. Floating point inputs
+are no longer scaled from `0..1`; instead they are treated in the same units as
+integers. If the alpha channel is omitted it defaults to `255`.
 
 ```ruby
-ImageUtil::Color[0.5] # => #808080
+ImageUtil::Color[128.5] # => #808080
 ImageUtil::Color[:red] # => #ff0000
 ImageUtil::Color["#fc0"] # => #ffcc00
 ```
@@ -94,32 +122,45 @@ patch = img[0..1, 0..1]
 For instance, you can extract a region, edit it and paste it back:
 
 ```ruby
-img = ImageUtil::Image.new(4, 4) { [0, 0, 0] }
-corner = img[0..1, 0..1]
+img = ImageUtil::Image.new(128, 128) { [0, 0, 0] }
+corner = img[0..32, 0..32]
 corner.all = :green
-img[0..1, 0..1] = corner
+img[0..32, 0..32] = corner
 img[2, 2] = :yellow
-img.to_file("pixel_patch.png", :png)
+# img.to_file("pixel_patch.png", :png)
+img
 ```
 
+![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`
+`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
+# create an all-black image
+img = ImageUtil::Image.new(128, 128) { :black }
+
 # fill a checkerboard pattern
-img = ImageUtil::Image.new(8, 8) { :white }
-img.set_each_pixel_by_location do |x, y|
-  :black if (x + y).odd?
+img.set_each_pixel_by_location! do |x, y|
+  :red if (x + y).odd?
 end
 
-# count how many black pixels were set
-black = img.each_pixel.count { |c| c == :black }
+# count how many red pixels were set
+black = img.each_pixel.count { |c| c == :red }
+
+# display img in terminal
+img
 ```
 
+![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`.
 
 ## Filters
@@ -132,8 +173,12 @@ modifies the image in place while the non-bang version returns a copy.
 Flatten an RGBA image on a solid color.
 
 ```ruby
+# create a transparent image gradient containing shades of red only
 img = ImageUtil::Image.new(128, 128) { |x, y| [255, 0, 0, x + y] }
-img.background([0, 0, 255])
+
+# put it on a blue background
+img.background!([0, 0, 255])
+# img.background([0, 0, 255]) # returns a new image
 ```
 
 ![Background example](docs/samples/background.png)
@@ -169,23 +214,77 @@ img.draw_circle!([64, 64], 30, :blue)
 Scale an image to new dimensions.
 
 ```ruby
-img = ImageUtil::Image.new(256, 256) { |x, y| [x, y, 30] }
-img[70, 70] = img.resize(64, 64)
+img = ImageUtil::Image.new(128, 128) { |x, y| [x, y, 30] }
+img[20, 20] = img.resize(64, 64)
 img
+# img.resize!(64, 64) # modifies in place
 ```
 
 ![Resize example](docs/samples/resize.png)
 
-### Dither
+### Palette
 
 Reduce the image to a limited palette.
 
 ```ruby
-img = ImageUtil::Image.new(256, 64) { |x, y| [x, y * 4, 200] }
-img.dither(8)
+img = ImageUtil::Image.new(128, 128) { |x, y| [x * 2, y * 2, 200] }
+img.palette_reduce(64)
 ```
 
-![Dither example](docs/samples/dither.png)
+![Palette reduce example](docs/samples/pdither.png)
+
+### Transform
+
+Rotate or flip an image.
+
+```ruby
+img = ImageUtil::Image.new(128, 128) { |x, y| [x, y, 0] }
+img.flip!(:x)
+img.rotate!(90)
+# img.rotate!(90, axes: [:x, :z])
+```
+
+![Transform example](docs/samples/transform.png)
+
+### Colors
+
+Multiply all pixels by a color.
+
+```ruby
+img = ImageUtil::Image.new(128, 128) { [255, 255, 255, 128] }
+img * :red
+```
+
+![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)
+```
+
+![Bitmap text example](docs/samples/bitmap_text.png)
+
+### Redimension
+
+Change how many dimensions an image has or adjust their size.
+
+```ruby
+img = ImageUtil::Image.new(64, 64) { :white }
+img.redimension!(128, 128) # can also add additional dimensions
+img.background(:blue)
+```
+
+![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
 
@@ -193,6 +292,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

data/lib/image_util/cli.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module ImageUtil
+  class CLI < Thor
+    desc "support", "Display codec support, default codecs and terminal features"
+    def support
+      width = (codec_names + format_names).map(&:length).max
+      use_color = Terminal.detect_support.include?(:tty)
+
+      puts "Codecs:"
+      codec_names.each do |name|
+        mod = Codec.const_get(name)
+        supported = mod.supported?
+        status = supported ? color("supported", 32, use_color) : color("not supported", 31, use_color)
+        puts format("  %-#{width}s  %s", name, status)
+      end
+
+      puts "\nFormats:"
+      format_names.each do |fmt|
+        codec = default_codec(fmt)
+        codec_name = codec ? color(codec.to_s, 32, use_color) : color("none", 31, use_color)
+        puts format("  %-#{width}s  %s", fmt, codec_name)
+      end
+
+      puts "\nTerminal features:"
+      Terminal.detect_support.each do |feat|
+        puts "  #{color(feat, 34, use_color)}"
+      end
+    end
+
+    no_commands do
+      def codec_names = Codec.constants.select { |name| Codec.const_get(name).respond_to?(:supported?) }
+      def format_names = (Codec.encoders + Codec.decoders).flat_map { |r| r[:formats] }.uniq.sort
+
+      def default_codec(fmt)
+        Codec.encoders.each do |r|
+          next unless r[:formats].include?(fmt.to_s)
+
+          codec_mod = Codec.const_get(r[:codec])
+          next if codec_mod.respond_to?(:supported?) && !codec_mod.supported?(fmt.to_sym)
+
+          return r[:codec]
+        end
+        nil
+      end
+
+      def color(text, code, enable)
+        enable ? "\e[#{code}m#{text}\e[0m" : text
+      end
+    end
+  end
+end

data/lib/image_util/codec/chunky_png.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module ImageUtil
+  module Codec
+    module ChunkyPng
+      SUPPORTED_FORMATS = [:png].freeze
+
+      extend Guard
+
+      begin
+        require "chunky_png"
+        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, "chunky_png not available" unless AVAILABLE
+
+        guard_2d_image!(image)
+        guard_8bit_colors!(image)
+
+        raw = if image.channels == 4
+                image.buffer.get_string
+              else
+                data = String.new(capacity: image.width * image.height * 4)
+                buf = image.buffer
+                idx = 0
+                step = buf.pixel_bytes
+                image.height.times do
+                  image.width.times do
+                    color = buf.get_index(idx)
+                    data << color[0].chr << color[1].chr << color[2].chr << 255.chr
+                    idx += step
+                  end
+                end
+                data
+              end
+
+        png = ::ChunkyPNG::Image.from_rgba_stream(image.width, image.height, raw)
+        png.to_blob
+      end
+
+      def decode(format, data)
+        guard_supported_format!(format, SUPPORTED_FORMATS)
+        raise UnsupportedFormatError, "chunky_png not available" unless AVAILABLE
+
+        png = ::ChunkyPNG::Image.from_blob(data)
+        raw = png.to_rgba_stream
+        io_buf = IO::Buffer.for(raw)
+        buf = Image::Buffer.new([png.width, png.height], 8, 4, io_buf)
+        Image.from_buffer(buf)
+      end
+    end
+  end
+end