retouch 0.3.0 → 0.3.1

data/lib/retouch/kernels/lut.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Retouch
+  module Kernels
+    module LUT
+      module_function
+
+      def apply(image, operation, value = nil, amount: 1.0)
+        bytes = image.bytes.dup
+        number = value.nil? || operation.to_sym == :tint ? nil : Float(value)
+        raise ArgumentError, "value must be finite" if number && !number.finite?
+
+        case operation.to_sym
+        when :grayscale
+          bytes.bytes.each_slice(4).with_index do |(red, green, blue, _alpha), index|
+            gray = (((red * 2126) + (green * 7152) + (blue * 722)) / 10_000.0).round
+            bytes.setbyte(index * 4, gray)
+            bytes.setbyte((index * 4) + 1, gray)
+            bytes.setbyte((index * 4) + 2, gray)
+          end
+        when :invert
+          lut = Array.new(256) { |channel| 255 - channel }
+          transform_rgb(bytes) { |channel| lut[channel] }
+        when :brightness
+          raise ArgumentError, "brightness must be between -255 and 255" unless number&.between?(-255, 255)
+
+          lut = Array.new(256) { |channel| (channel + number).round.clamp(0, 255) }
+          transform_rgb(bytes) { |channel| lut[channel] }
+        when :contrast
+          raise ArgumentError, "contrast must be between 0 and 10" unless number&.between?(0, 10)
+
+          lut = Array.new(256) { |channel| (((channel - 127.5) * number) + 127.5).round.clamp(0, 255) }
+          transform_rgb(bytes) { |channel| lut[channel] }
+        when :gamma
+          raise ArgumentError, "gamma must be positive and at most 10" unless number&.positive? && number <= 10
+
+          lut = Array.new(256) { |channel| (255 * ((channel / 255.0)**(1.0 / number))).round }
+          transform_rgb(bytes) { |channel| lut[channel] }
+        when :saturate
+          raise ArgumentError, "saturation must be between 0 and 10" unless number&.between?(0, 10)
+
+          bytes.bytes.each_slice(4).with_index do |(red, green, blue, _alpha), index|
+            gray = (red * 0.2126) + (green * 0.7152) + (blue * 0.0722)
+            [red, green, blue].each_with_index do |channel, component|
+              bytes.setbyte((index * 4) + component, (gray + ((channel - gray) * number)).round.clamp(0, 255))
+            end
+          end
+        when :tint
+          raise ArgumentError, "tint amount must be between 0 and 1" unless amount.is_a?(Numeric) && amount.finite? && amount.between?(0, 1)
+
+          tint = Tessel::Color.pack(value).bytes.first(3)
+          bytes.bytes.each_slice(4).with_index do |(red, green, blue, _alpha), index|
+            [red, green, blue].each_with_index do |channel, component|
+              bytes.setbyte((index * 4) + component, ((channel * (1 - amount)) + (tint[component] * amount)).round)
+            end
+          end
+        when :opacity
+          raise ArgumentError, "opacity must be between 0 and 1" unless number&.between?(0, 1)
+
+          (3...bytes.bytesize).step(4) { |index| bytes.setbyte(index, (bytes.getbyte(index) * number).round) }
+        else
+          raise ArgumentError, "unknown LUT operation: #{operation}"
+        end
+        Tessel::Image.from_rgba(image.width, image.height, bytes, metadata: image.metadata)
+      end
+
+      def transform_rgb(bytes)
+        bytes.bytesize.times do |index|
+          bytes.setbyte(index, yield(bytes.getbyte(index))) if index % 4 != 3
+        end
+      end
+      private_class_method :transform_rgb
+    end
+  end
+end

data/lib/retouch/operations/color.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Retouch
+  module Operations
+    module_function
+
+    %i[grayscale invert brightness contrast gamma saturate opacity].each do |operation|
+      define_method(operation) do |image, value = nil|
+        Kernels::LUT.apply(image, operation, value)
+      end
+    end
+
+    def tint(image, color, amount: 1.0)
+      Kernels::LUT.apply(image, :tint, color, amount: Float(amount))
+    end
+
+    def quantize(image, colors: 256, dither: :none, palette: nil)
+      Kernels.quantize(image, colors:, dither:, palette:)
+    end
+  end
+end

data/lib/retouch/operations/draw.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module Retouch
+  module Operations
+    module_function
+
+    BLENDS = %i[normal multiply screen overlay darken lighten add].freeze
+
+    def overlay(image, source, x: nil, y: nil, gravity: :center, opacity: 1.0, mode: :normal)
+      source = ImageIO.read(source) unless source.is_a?(Tessel::Image)
+      opacity = Float(opacity)
+      mode = mode.to_sym
+      raise ArgumentError, "opacity must be between 0 and 1" unless opacity.finite? && opacity.between?(0, 1)
+      raise ArgumentError, "unknown blend mode: #{mode}" unless BLENDS.include?(mode)
+
+      offset_x, offset_y = Gravity.offset(image.width, image.height, source.width, source.height, gravity)
+      offset_x = Integer(x) unless x.nil?
+      offset_y = Integer(y) unless y.nil?
+      output = image.dup
+      source.height.times do |source_y|
+        source.width.times do |source_x|
+          target_x = source_x + offset_x
+          target_y = source_y + offset_y
+          next unless target_x.between?(0, image.width - 1) && target_y.between?(0, image.height - 1)
+
+          source_pixel = source[source_x, source_y]
+          source_pixel[3] = (source_pixel[3] * opacity).round
+          next if source_pixel[3].zero?
+
+          output[target_x, target_y] = blend_pixel(output[target_x, target_y], source_pixel, mode)
+        end
+      end
+      output
+    end
+
+    def watermark(image, source, **options)
+      overlay(image, source, **options)
+    end
+
+    def rect(image, x, y, width, height, color = "#ffffff", fill: false)
+      x = Integer(x)
+      y = Integer(y)
+      width = Integer(width)
+      height = Integer(height)
+      raise ArgumentError, "rectangle dimensions must be positive" unless width.positive? && height.positive?
+
+      output = image.dup
+      if fill
+        output.fill_rect(x, y, width, height, color, blend: :alpha)
+      else
+        output.fill_rect(x, y, width, 1, color, blend: :alpha)
+        output.fill_rect(x, y + height - 1, width, 1, color, blend: :alpha)
+        output.fill_rect(x, y, 1, height, color, blend: :alpha)
+        output.fill_rect(x + width - 1, y, 1, height, color, blend: :alpha)
+      end
+      output
+    end
+
+    def arrow(image, x1, y1, x2, y2, color = "#ffffff", width: 1, head: 8)
+      x1, y1, x2, y2 = [x1, y1, x2, y2].map { |value| Integer(value) }
+      width = Integer(width)
+      head = Float(head)
+      raise ArgumentError, "arrow width must be positive" unless width.positive?
+      raise ArgumentError, "arrow head length must be non-negative and finite" unless head.finite? && head >= 0
+
+      output = image.dup
+      draw_line(output, x1, y1, x2, y2, color, width)
+      distance = Math.hypot(x2 - x1, y2 - y1)
+      if head.positive? && distance.positive?
+        angle = Math.atan2(y2 - y1, x2 - x1)
+        [angle + (0.65 * Math::PI), angle - (0.65 * Math::PI)].each do |side|
+          draw_line(output, x2, y2, (x2 + (Math.cos(side) * head)).round, (y2 + (Math.sin(side) * head)).round, color, width)
+        end
+      end
+      output
+    end
+
+    def text(image, string, x: 0, y: 0, at: nil, size: 16, font: nil, color: "#ffffff", background: nil, padding: 4)
+      begin
+        require "glyphic"
+      rescue LoadError => e
+        raise Error, "text requires the glyphic gem (gem install glyphic)", cause: e
+      end
+      size = Integer(size)
+      raise ArgumentError, "font size must be positive" unless size.positive?
+
+      font_object = font ? Glyphic.load(font, size: Integer(size)) : Glyphic.default
+      rendered = font_object.render(String(string), color: Tessel::Color.pack(color).bytes)
+      if !font && size != font_object.line_height
+        scale = size.to_f / font_object.line_height
+        rendered = rendered.scale_nearest([(rendered.width * scale).round, 1].max, [(rendered.height * scale).round, 1].max)
+      end
+      text_width = rendered.width
+      text_height = rendered.height
+      padding = Integer(padding)
+      raise ArgumentError, "text padding must not be negative" if padding.negative?
+
+      if at
+        x, y = Gravity.offset(image.width, image.height, text_width + (padding * 2), text_height + (padding * 2), at)
+        x += padding
+        y += padding
+      else
+        x = Integer(x)
+        y = Integer(y)
+      end
+      output = image.dup
+      output.fill_rect(x - padding, y - padding, text_width + (padding * 2), text_height + (padding * 2), background, blend: :alpha) if background
+      output.blit(rendered, x, y)
+      output
+    end
+
+    def blend_pixel(destination, source, mode)
+      source_alpha = source[3] / 255.0
+      destination_alpha = destination[3] / 255.0
+      output_alpha = source_alpha + (destination_alpha * (1 - source_alpha))
+      return [0, 0, 0, 0] if output_alpha.zero?
+
+      rgb = 3.times.map do |channel|
+        source_color = source[channel] / 255.0
+        destination_color = destination[channel] / 255.0
+        blended = case mode
+                  when :normal then source_color
+                  when :multiply then source_color * destination_color
+                  when :screen then 1 - ((1 - source_color) * (1 - destination_color))
+                  when :overlay then destination_color <= 0.5 ? 2 * source_color * destination_color : 1 - (2 * (1 - source_color) * (1 - destination_color))
+                  when :darken then [source_color, destination_color].min
+                  when :lighten then [source_color, destination_color].max
+                  when :add then [source_color + destination_color, 1].min
+                  end
+        premultiplied = ((1 - source_alpha) * destination_alpha * destination_color) + ((1 - destination_alpha) * source_alpha * source_color) + (source_alpha * destination_alpha * blended)
+        (premultiplied / output_alpha * 255).round.clamp(0, 255)
+      end
+      [*rgb, (output_alpha * 255).round.clamp(0, 255)]
+    end
+    private_class_method :blend_pixel
+
+    def draw_line(image, x1, y1, x2, y2, color, width)
+      dx = (x2 - x1).abs
+      sx = x1 < x2 ? 1 : -1
+      dy = -(y2 - y1).abs
+      sy = y1 < y2 ? 1 : -1
+      error = dx + dy
+      loop do
+        image.fill_rect(x1 - (width / 2), y1 - (width / 2), width, width, color, blend: :alpha)
+        break if x1 == x2 && y1 == y2
+
+        doubled = 2 * error
+        if doubled >= dy
+          error += dy
+          x1 += sx
+        end
+        if doubled <= dx
+          error += dx
+          y1 += sy
+        end
+      end
+    end
+    private_class_method :draw_line
+  end
+end

data/lib/retouch/operations/filter.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Retouch
+  module Operations
+    module_function
+
+    def blur(image, sigma)
+      Kernels::Convolve.gaussian(image, sigma)
+    end
+
+    def sharpen(image, sigma, amount: 1.0)
+      amount = Float(amount)
+      raise ArgumentError, "sharpen amount must be between 0 and 10" unless amount.finite? && amount.between?(0, 10)
+
+      blurred = blur(image, sigma)
+      source = image.bytes
+      smooth = blurred.bytes
+      output = source.dup
+      (0...(image.width * image.height)).each do |index|
+        offset = index * 4
+        original_alpha = source.getbyte(offset + 3) / 255.0
+        smooth_alpha = smooth.getbyte(offset + 3) / 255.0
+        3.times do |channel|
+          original = source.getbyte(offset + channel) * original_alpha
+          blurred_color = smooth.getbyte(offset + channel) * smooth_alpha
+          sharpened = original + (amount * (original - blurred_color))
+          color = original_alpha.positive? ? (sharpened / original_alpha).round.clamp(0, 255) : 0
+          output.setbyte(offset + channel, color)
+        end
+      end
+      Tessel::Image.from_rgba(image.width, image.height, output, metadata: image.metadata)
+    end
+
+    def pixelate(image, size)
+      size = Integer(size)
+      raise ArgumentError, "pixel size must be positive" unless size.positive?
+      return image.dup if image.width.zero? || image.height.zero?
+
+      output = image.dup
+      (0...image.height).step(size) do |y|
+        height = [size, image.height - y].min
+        (0...image.width).step(size) do |x|
+          width = [size, image.width - x].min
+          alpha_sum = red = green = blue = 0.0
+          (y...(y + height)).each do |py|
+            (x...(x + width)).each do |px|
+              color = image[px, py]
+              alpha = color[3] / 255.0
+              red += color[0] * alpha
+              green += color[1] * alpha
+              blue += color[2] * alpha
+              alpha_sum += color[3]
+            end
+          end
+          count = width * height
+          alpha = (alpha_sum / count).round
+          color = alpha_sum.positive? ? [(red * 255 / alpha_sum).round, (green * 255 / alpha_sum).round, (blue * 255 / alpha_sum).round, alpha] : [0, 0, 0, 0]
+          output.fill_rect(x, y, width, height, color, blend: :copy)
+        end
+      end
+      output
+    end
+  end
+end

data/lib/retouch/operations/multiple.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+module Retouch
+  module Operations
+    module_function
+
+    def append(images, direction: :vertical, gap: 0, background: [0, 0, 0, 0])
+      images = validate_images(images)
+      direction = direction.to_sym
+      gap = Integer(gap)
+      raise ArgumentError, "direction must be vertical or horizontal" unless %i[vertical horizontal].include?(direction)
+      raise ArgumentError, "gap must not be negative" if gap.negative?
+
+      if direction == :vertical
+        width = images.map(&:width).max
+        height = images.sum(&:height) + (gap * (images.length - 1))
+      else
+        width = images.sum(&:width) + (gap * (images.length - 1))
+        height = images.map(&:height).max
+      end
+      output = Tessel::Image.new(width, height, fill: background)
+      x = y = 0
+      images.each do |image|
+        dx, dy = Gravity.offset(width, height, image.width, image.height, :center)
+        output.blit(image, direction == :vertical ? dx : x, direction == :vertical ? y : dy)
+        direction == :vertical ? y += image.height + gap : x += image.width + gap
+      end
+      output
+    end
+
+    def montage(images, columns: nil, cols: nil, gap: 0, background: [0, 0, 0, 0], labels: nil)
+      images = validate_images(images)
+      columns = Integer(columns || cols || Math.sqrt(images.length).ceil)
+      gap = Integer(gap)
+      raise ArgumentError, "columns must be positive" unless columns.positive?
+      raise ArgumentError, "gap must not be negative" if gap.negative?
+
+      column_widths = Array.new([images.length, columns].min, 0)
+      row_heights = Array.new((images.length.to_f / columns).ceil, 0)
+      images.each_with_index do |image, index|
+        column = index % columns
+        row = index / columns
+        column_widths[column] = [column_widths[column], image.width].max
+        row_heights[row] = [row_heights[row], image.height + (labels ? 15 : 0)].max
+      end
+      output = Tessel::Image.new(column_widths.sum + (gap * (column_widths.length - 1)), row_heights.sum + (gap * (row_heights.length - 1)), fill: background)
+      row_y = 0
+      row_heights.each_with_index do |row_height, row|
+        column_x = 0
+        column_widths.each_with_index do |column_width, column|
+          index = (row * columns) + column
+          break unless images[index]
+
+          image = images[index]
+          image_y = row_y + ((row_height - image.height - (labels ? 15 : 0)) / 2)
+          output.blit(image, column_x + ((column_width - image.width) / 2), image_y)
+          if labels
+            label = labels == true ? index.to_s : String(labels.fetch(index))
+            output.fill_rect(column_x, row_y + row_height - 15, column_width, 15, [0, 0, 0, 192], blend: :alpha)
+            output = text(output, label, x: column_x + 3, y: row_y + row_height - 12, size: 9, color: "#ffffff")
+          end
+          column_x += column_width + gap
+        end
+        row_y += row_height + gap
+      end
+      output
+    end
+
+    def spritesheet(images, max_width: 2048, gap: 0, background: [0, 0, 0, 0])
+      images = validate_images(images)
+      max_width = Integer(max_width)
+      gap = Integer(gap)
+      raise ArgumentError, "max_width must be positive" unless max_width.positive?
+      raise ArgumentError, "gap must not be negative" if gap.negative?
+      raise ArgumentError, "an image is wider than max_width" if images.any? { |image| image.width > max_width }
+
+      bound_height = images.sum(&:height) + (gap * images.length)
+      free = [{ x: 0, y: 0, width: max_width, height: bound_height }]
+      placements = Array.new(images.length)
+      images.each_with_index.sort_by { |image, index| [-image.width * image.height, -[image.width, image.height].max, index] }.each do |image, index|
+        packed_width = image.width + gap
+        packed_height = image.height + gap
+        position = free.select { |rect| packed_width <= rect[:width] && packed_height <= rect[:height] }
+                       .map do |rect|
+          leftover_width = rect[:width] - packed_width
+          leftover_height = rect[:height] - packed_height
+          score = [
+            [leftover_width, leftover_height].min,
+            rect[:y],
+            rect[:x],
+            [leftover_width, leftover_height].max
+          ]
+          [score, rect[:x], rect[:y]]
+        end.min_by(&:first)
+        raise ArgumentError, "could not pack images within max_width" unless position
+
+        _score, x, y = position
+        packed = { x:, y:, width: packed_width, height: packed_height }
+        placements[index] = { index:, x:, y:, width: image.width, height: image.height }
+        free = split_free_rectangles(free, packed)
+      end
+      used_width = placements.map { |item| item[:x] + item[:width] }.max || 0
+      height = placements.map { |item| item[:y] + item[:height] }.max || 0
+      output = Tessel::Image.new(used_width, height, fill: background)
+      images.zip(placements).each { |image, item| output.blit(image, item[:x], item[:y]) }
+      [output, placements]
+    end
+
+    def diff(expected, actual, threshold: 0, color: "#ff00ff")
+      raise TypeError, "expected and actual must be Tessel::Image values" unless expected.is_a?(Tessel::Image) && actual.is_a?(Tessel::Image)
+      raise ArgumentError, "images must have the same dimensions" unless expected.width == actual.width && expected.height == actual.height
+
+      threshold = Float(threshold)
+      raise ArgumentError, "threshold must be between 0 and 255" unless threshold.finite? && threshold.between?(0, 255)
+
+      marker = Tessel::Color.pack(color).bytes
+      output = Tessel::Image.new(expected.width, expected.height)
+      different = 0
+      expected.height.times do |y|
+        expected.width.times do |x|
+          left = expected[x, y]
+          right = actual[x, y]
+          if left.zip(right).map { |a, b| (a - b).abs }.max > threshold
+            output[x, y] = marker
+            different += 1
+          end
+        end
+      end
+      { image: output, pixels: different, total: expected.width * expected.height,
+        rate: expected.width.zero? || expected.height.zero? ? 0.0 : different.to_f / (expected.width * expected.height) }
+    end
+
+    def animate(frames, path, fps: nil, delay: nil, loop: true, colors: 256, palette: :global, dither: :floyd_steinberg)
+      require_flipbook
+      Flipbook.write(path, validate_images(frames), fps:, delay:, loop:, colors:, palette:, dither:)
+    end
+
+    def open_gif(path, frame: :all, max_pixels: 16_384 * 16_384, max_frames: 10_000, max_total_pixels: 100_000_000)
+      require_flipbook
+      frames = Flipbook.read(path, max_pixels:, max_frames:, max_total_pixels:)
+      return frames if frame == :all
+
+      frames.fetch(frame == :first ? 0 : Integer(frame))
+    end
+
+    def validate_images(images)
+      images = Array(images)
+      raise ArgumentError, "at least one image is required" if images.empty?
+      raise TypeError, "images must contain only Tessel::Image values" unless images.all?(Tessel::Image)
+      raise ArgumentError, "images must have positive dimensions" unless images.all? { |image| image.width.positive? && image.height.positive? }
+
+      images
+    end
+    private_class_method :validate_images
+
+    def split_free_rectangles(free, placed)
+      split = free.flat_map do |rect|
+        overlaps = placed[:x] < rect[:x] + rect[:width] && placed[:x] + placed[:width] > rect[:x] &&
+                   placed[:y] < rect[:y] + rect[:height] && placed[:y] + placed[:height] > rect[:y]
+        next [rect] unless overlaps
+
+        pieces = []
+        pieces << { x: rect[:x], y: rect[:y], width: rect[:width], height: placed[:y] - rect[:y] } if placed[:y] > rect[:y]
+        pieces << { x: rect[:x], y: placed[:y] + placed[:height], width: rect[:width], height: rect[:y] + rect[:height] - placed[:y] - placed[:height] } if placed[:y] + placed[:height] < rect[:y] + rect[:height]
+        pieces << { x: rect[:x], y: rect[:y], width: placed[:x] - rect[:x], height: rect[:height] } if placed[:x] > rect[:x]
+        pieces << { x: placed[:x] + placed[:width], y: rect[:y], width: rect[:x] + rect[:width] - placed[:x] - placed[:width], height: rect[:height] } if placed[:x] + placed[:width] < rect[:x] + rect[:width]
+        pieces.select { |piece| piece[:width].positive? && piece[:height].positive? }
+      end
+      # ponytail: free-rectangle pruning is O(n²); replace it if large atlases make it slow.
+      split.reject.with_index do |rect, index|
+        split.each_with_index.any? do |other, other_index|
+          next false if index == other_index
+
+          contained = other[:x] <= rect[:x] && other[:y] <= rect[:y] &&
+                      other[:x] + other[:width] >= rect[:x] + rect[:width] &&
+                      other[:y] + other[:height] >= rect[:y] + rect[:height]
+          contained && (other != rect || other_index < index)
+        end
+      end
+    end
+    private_class_method :split_free_rectangles
+
+    def require_flipbook
+      require "flipbook"
+      version = Gem::Version.new(Flipbook::VERSION)
+      raise Error, "GIF/APNG support requires flipbook >= 0.4.0 (found #{version})" if version < Gem::Version.new("0.4.0")
+    rescue LoadError => e
+      raise Error, "GIF/APNG support requires flipbook >= 0.4.0 (gem install flipbook)", cause: e
+    end
+    private_class_method :require_flipbook
+  end
+end