retouch 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 79c42e7a96d4184640a68bfd3205bf2d89c99bae8849f5c7e77fafd258a97738
+  data.tar.gz: 99fd548525bcf5374f83a559746061a4e6eb33aca77679f15e21a6b3ae4d913e
+SHA512:
+  metadata.gz: 6187dc735d131af9ad3e6dc57f4cdb4fac3eb3f6787804a0498da4fbb21aafb8bb571b5edbc98eb4dec242c8c66d805eedcec03f4326d50e0b39f72f68638154
+  data.tar.gz: b11da4111c899723b42cadf4cc87196bf86f4cb83d39c7ec506f9d08010a2b96ff8df6db8da04b4a5fae7885c702c2c6c77c3d0138b4d48f5d893fd700d06a69

data/.rubocop.yml

@@ -0,0 +1,35 @@
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.1
+  SuggestExtensions: false
+  CacheRootDirectory: tmp/rubocop-cache
+  Exclude:
+    - vendor/**/*
+    - tmp/**/*
+
+Layout/LineLength:
+  Max: 300
+
+Metrics:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: false
+
+Style/Attr:
+  Enabled: false
+
+Naming/MethodParameterName:
+  Enabled: false
+
+Style/MultilineBlockChain:
+  Enabled: false
+
+Gemspec/DevelopmentDependencies:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+All notable changes to Retouch are recorded here.
+
+## [0.1.0] - 2026-09-25
+
+Initial release

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+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,56 @@
+<h1 align="center">Retouch</h1>
+
+<p align="center">Resize and reshape images with a small Ruby API and CLI.</p>
+
+<p align="center">
+  <a href="https://github.com/rbgfx/retouch/actions/workflows/main.yml"><img src="https://github.com/rbgfx/retouch/actions/workflows/main.yml/badge.svg" alt="CI"></a>
+  <a href="https://www.ruby-lang.org/"><img src="https://img.shields.io/badge/ruby-%3E%3D3.1-CC342D?logo=ruby&amp;logoColor=white" alt="Ruby 3.1+"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-750014.svg" alt="MIT license"></a>
+</p>
+
+Retouch uses [Tessel](https://github.com/rbgfx/tessel) to read and write PNG, PPM, and BMP images. Its lazy pipelines cover resizing, cropping, rotation, borders, padding, extending, and trimming.
+
+## Install
+
+Until the first RubyGems release, add the repository to your Gemfile:
+
+```ruby
+gem "retouch", github: "rbgfx/retouch"
+```
+
+## Ruby API
+
+```ruby
+require "retouch"
+
+Retouch.open("screenshot.png")
+  .resize("640x")
+  .border(1, "#303846")
+  .save("small.png")
+```
+
+Pipelines defer work until `to_image` or `save` and leave the source image unchanged.
+
+## CLI
+
+```sh
+retouch screenshot.png resize 640x --filter lanczos3 -o small.png
+retouch screenshot.png crop 320x200+40+20 -o crop.png
+retouch screenshot.png rotate 90 -o rotated.png
+retouch info screenshot.png
+```
+
+Geometry accepts `WIDTHxHEIGHT`, `WIDTHx`, `xHEIGHT`, percentages, `!` to stretch, `^` to cover, and `>` to shrink only. Crop offsets may be positive or negative. Resize filters are `nearest`, `bilinear`, `bicubic`, and `lanczos3`.
+
+Outputs are protected from accidental overwrite; use `--force` to replace one. `--dry-run`, `--verbose`, `--quiet`, `--strip`, and `--level 0..9` control a command.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake verify
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/Rakefile

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+require "rbs"
+require "rubocop/rake_task"
+
+Rake::TestTask.new(:test) do |task|
+  task.libs << "lib"
+  task.pattern = "test/**/*_test.rb"
+end
+RuboCop::RakeTask.new(:lint) { |task| task.options = ["--cache", "false"] }
+
+task :types do
+  sh "bundle exec rbs -I sig validate"
+end
+
+task verify: %i[lint test types]
+task default: :verify

data/bench/retouch.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "retouch"
+
+def measure(name)
+  started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  yield
+  elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+  puts format("%<name>s %<elapsed>.3fs", name:, elapsed:)
+end
+
+puts "YJIT: #{RubyVM::YJIT.enabled?}"
+image = Tessel::Image.new(1920, 1080, fill: [80, 120, 160, 255])
+measure("1920x1080 -> 960x540 bilinear") { Retouch::Operations.resize(image, "960x540", filter: :bilinear) }
+measure("1920x1080 -> 960x540 lanczos3") { Retouch::Operations.resize(image, "960x540", filter: :lanczos3) }
+measure("1920x1080 -> 960x540 nearest") { Retouch::Operations.resize(image, "960x540", filter: :nearest) }
+measure("256x256 -> 1024x1024 nearest") do
+  Retouch::Operations.resize(Tessel::Image.new(256, 256), "400%", filter: :nearest)
+end

data/exe/retouch

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "retouch"
+
+exit Retouch::CLI.run(ARGV)

data/lib/retouch/cli.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+
+module Retouch
+  class CLI
+    OPERATIONS = %w[resize thumbnail crop flip flop rotate pad extend border trim].freeze
+
+    def self.run(argv, out: $stdout, err: $stderr)
+      new(argv, out:, err:).run
+    rescue ArgumentError, OptionParser::ParseError => e
+      err.puts("retouch: #{e.message}")
+      2
+    end
+
+    def initialize(argv, out:, err:)
+      @args = argv.dup
+      @out = out
+      @err = err
+      @options = { level: 6 }
+      read_global_options
+      raise ArgumentError, "PNG level must be between 0 and 9" unless @options[:level].between?(0, 9)
+    end
+
+    def run
+      return help if @options[:help] || @args.empty?
+      return info_command if @args.first == "info"
+      return help(@args[1]) if @args.first == "help"
+
+      operation_at = @args.index { |token| OPERATIONS.include?(token) }
+      return fail_usage("missing operation") unless operation_at
+
+      inputs = @args.shift(operation_at)
+      return fail_usage("exactly one input file is required") unless inputs.one?
+      return fail_usage("an output path with -o is required") unless @options[:output]
+
+      input = inputs.first
+      operations = parse_operations(@args)
+      return announce("retouch #{input} #{operations.map(&:first).join(" ")} -o #{@options[:output]}") if @options[:dry_run]
+      raise Error, "input file does not exist: #{input}" unless File.file?(input)
+      raise Error, "refusing to overwrite #{@options[:output]}; use --force" if File.exist?(@options[:output]) && !@options[:force]
+
+      FileUtils.mkdir_p(File.dirname(@options[:output])) unless File.dirname(@options[:output]) == "."
+      pipeline = operations.reduce(Retouch.open(input)) do |current, (name, args, options)|
+        announce("applying #{name}") if @options[:verbose]
+        current.public_send(name, *args, **options)
+      end
+      pipeline.save(@options[:output], level: @options[:level], strip: @options[:strip])
+      announce(@options[:output])
+      0
+    rescue ArgumentError, OptionParser::ParseError
+      raise
+    rescue StandardError => e
+      @err.puts("retouch: #{e.message}")
+      @err.puts(e.backtrace.first) if @options[:verbose]
+      1
+    end
+
+    private
+
+    def read_global_options
+      remaining = []
+      until @args.empty?
+        token = @args.shift
+        case token
+        when "-h", "--help" then @options[:help] = true
+        when "-o", "--output" then @options[:output] = require_value(token)
+        when "--dry-run" then @options[:dry_run] = true
+        when "--verbose" then @options[:verbose] = true
+        when "--quiet" then @options[:quiet] = true
+        when "--force" then @options[:force] = true
+        when "--strip" then @options[:strip] = true
+        when "--level" then @options[:level] = Integer(require_value(token))
+        else remaining << token
+        end
+      end
+      @args = remaining
+    end
+
+    def require_value(option)
+      value = @args.shift
+      raise OptionParser::MissingArgument, option unless value
+
+      value
+    end
+
+    def parse_operations(tokens)
+      operations = []
+      until tokens.empty?
+        name = tokens.shift
+        raise ArgumentError, "unknown operation: #{name}" unless OPERATIONS.include?(name)
+
+        args, options = case name
+                        when "resize", "thumbnail", "crop" then [[required(tokens, "geometry")], read_options(tokens, filter: :symbol, gravity: :symbol)]
+                        when "rotate" then [[required(tokens, name)], read_options(tokens, background: :string)]
+                        when "pad" then [[required(tokens, name)], read_options(tokens, color: :string)]
+                        when "extend" then [[required(tokens, name), required(tokens, name)], read_options(tokens, color: :string, gravity: :symbol)]
+                        when "border" then [[required(tokens, name), tokens.first&.start_with?("#") ? tokens.shift : "#000000"], {}]
+                        when "trim" then [[], read_options(tokens, fuzz: :integer, color: :string)]
+                        when "flip", "flop" then [[], {}]
+                        end
+        operations << [name, args, options]
+      end
+      operations
+    end
+
+    def read_options(tokens, specification)
+      options = {}
+      while tokens.first&.start_with?("--")
+        option = tokens.shift.delete_prefix("--").tr("-", "_").to_sym
+        type = specification[option]
+        raise OptionParser::InvalidOption, "--#{option}" unless type
+
+        value = required(tokens, option)
+        options[option] = case type
+                          when :integer then Integer(value)
+                          when :symbol then value.tr("-", "_").to_sym
+                          else value
+                          end
+      end
+      options
+    end
+
+    def required(tokens, name)
+      value = tokens.shift
+      raise OptionParser::MissingArgument, name unless value
+
+      value
+    end
+
+    def info_command
+      @args.shift
+      return fail_usage("info expects one input file") unless @args.one?
+
+      path = @args.first
+      announce(JSON.pretty_generate({ path:, **Operations.info(ImageIO.read(path)) }))
+      0
+    rescue StandardError => e
+      @err.puts("retouch: #{e.message}")
+      1
+    end
+
+    def fail_usage(message)
+      @err.puts("retouch: #{message}")
+      @err.puts("Run 'retouch --help' for usage.")
+      2
+    end
+
+    def announce(message)
+      @out.puts(message) unless @options[:quiet]
+      0
+    end
+
+    def help(operation = nil)
+      if operation
+        raise ArgumentError, "unknown operation help: #{operation}" unless OPERATIONS.include?(operation)
+
+        @out.puts("retouch INPUT #{operation} [ARGUMENTS] -o OUTPUT")
+        return 0
+      end
+      @out.puts <<~HELP
+        Retouch resizes and reshapes PNG, PPM, and BMP images.
+
+        Usage: retouch INPUT OPERATION [ARGUMENTS] -o OUTPUT
+               retouch help OPERATION
+               retouch info INPUT
+
+        Operations: resize thumbnail crop rotate flip flop pad extend border trim
+        Options: -o, --output PATH  --force  --dry-run  --verbose  --quiet
+                 --strip  --level 0..9  -h, --help
+      HELP
+      0
+    end
+  end
+end

data/lib/retouch/geometry.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Retouch
+  class Geometry
+    attr_reader :width, :height, :offset_x, :offset_y, :mode
+
+    def self.parse(value)
+      text = String(value)
+      match = /\A(?:(?<width>\d+(?:\.\d+)?%?)?x(?<height>\d+(?:\.\d+)?%?)?|(?<single>\d+(?:\.\d+)?%))(?<mode>[!^>])?(?<x>[+-]\d+)?(?<y>[+-]\d+)?\z/.match(text)
+      raise ArgumentError, "invalid geometry: #{text}" unless match
+
+      width = match[:width] || match[:single]
+      height = match[:height] || match[:single]
+      raise ArgumentError, "geometry needs at least one dimension" unless width || height
+
+      mode = { "!" => :stretch, "^" => :cover, ">" => :shrink }.fetch(match[:mode], :fit)
+      raise ArgumentError, "geometry needs both offsets" if match[:x].nil? != match[:y].nil?
+
+      new(width && dimension(width), height && dimension(height), (match[:x] || 0).to_i, (match[:y] || 0).to_i, mode)
+    end
+
+    def self.dimension(value)
+      number = Float(value.delete_suffix("%"), exception: false)
+      raise ArgumentError, "geometry dimensions must be positive" unless number&.positive?
+
+      value.end_with?("%") ? number / 100.0 : number.round
+    end
+    private_class_method :dimension
+
+    def initialize(width, height, offset_x, offset_y, mode)
+      @width = width
+      @height = height
+      @offset_x = offset_x
+      @offset_y = offset_y
+      @mode = mode
+    end
+
+    def crop_size(source_width, source_height)
+      raise ArgumentError, "crop geometry needs both dimensions" unless width && height
+
+      [scaled_dimension(source_width, width), scaled_dimension(source_height, height)]
+    end
+
+    def target_size(source_width, source_height)
+      width_ratio = width.is_a?(Float) ? width : nil
+      height_ratio = height.is_a?(Float) ? height : nil
+      target_width = width_ratio ? source_width * width_ratio : width
+      target_height = height_ratio ? source_height * height_ratio : height
+      return [scaled_dimension(source_width, width_ratio), scaled_dimension(source_height, height_ratio)] if width_ratio && height_ratio
+      return [scaled_dimension(source_width, target_width), scaled_dimension(source_height, target_height)] if mode == :stretch && target_width && target_height
+
+      scale = if target_width && target_height
+                horizontal = target_width.to_f / source_width
+                vertical = target_height.to_f / source_height
+                mode == :cover ? [horizontal, vertical].max : [horizontal, vertical].min
+              elsif target_width
+                target_width.to_f / source_width
+              elsif target_height
+                target_height.to_f / source_height
+              else
+                1.0
+              end
+      scale = [scale, 1.0].min if mode == :shrink
+      [(source_width * scale).round.clamp(1, 1_000_000), (source_height * scale).round.clamp(1, 1_000_000)]
+    end
+
+    private
+
+    def scaled_dimension(source, value)
+      (value.is_a?(Float) ? source * value : value).round.clamp(1, 1_000_000)
+    end
+  end
+end

data/lib/retouch/gravity.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Retouch
+  module Gravity
+    DIRECTIONS = {
+      north_west: [0, 0], north: [0.5, 0], north_east: [1, 0],
+      west: [0, 0.5], center: [0.5, 0.5], east: [1, 0.5],
+      south_west: [0, 1], south: [0.5, 1], south_east: [1, 1]
+    }.freeze
+
+    module_function
+
+    def offset(container_width, container_height, content_width, content_height, gravity = :center)
+      horizontal, vertical = DIRECTIONS.fetch(gravity.to_s.tr("-", "_").to_sym) { raise ArgumentError, "unknown gravity: #{gravity}" }
+      [(container_width - content_width) * horizontal, (container_height - content_height) * vertical].map(&:round)
+    end
+  end
+end

data/lib/retouch/io.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Retouch
+  module ImageIO
+    module_function
+
+    def read(path)
+      signature = File.binread(path, 8)
+      format = if signature.start_with?(Tessel::SIGNATURE)
+                 "PNG"
+               elsif signature.start_with?("P3", "P6")
+                 "PPM"
+               elsif signature.start_with?("BM")
+                 "BMP"
+               end
+      with_format(Tessel.read(path), format || "unknown")
+    rescue Tessel::UnsupportedError => e
+      raise Error, "unsupported image format for #{path}: #{e.message}", cause: e
+    end
+
+    def write(image, path, level: 6, strip: false)
+      raise TypeError, "image must be a Tessel::Image" unless image.is_a?(Tessel::Image)
+
+      image = Tessel::Image.from_rgba(image.width, image.height, image.bytes) if strip
+      extension = File.extname(path).downcase
+      case extension
+      when ".png"
+        image.write(path, level: Integer(level))
+      when ".ppm", ".pnm"
+        image.write(path, binary: true)
+      when ".bmp"
+        image.write(path)
+      else
+        raise Error, "unsupported output format: #{extension.empty? ? "(no extension)" : extension}"
+      end
+      path
+    rescue ArgumentError, Tessel::Error => e
+      raise Error, e.message, cause: e
+    end
+
+    def with_format(image, format)
+      metadata = image.metadata.merge("format" => format)
+      Tessel::Image.from_rgba(image.width, image.height, image.bytes, metadata:)
+    end
+  end
+end

data/lib/retouch/operations.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+module Retouch
+  module Operations
+    module_function
+
+    def apply(image, name, *arguments, **options)
+      raise TypeError, "image must be a Tessel::Image" unless image.is_a?(Tessel::Image)
+
+      method = name.to_sym
+      raise ArgumentError, "unknown operation: #{name}" unless respond_to?(method)
+
+      public_send(method, image, *arguments, **options)
+    end
+
+    def info(image)
+      colors = {}
+      alpha = false
+      image.bytes.bytes.each_slice(4) do |r, g, b, a|
+        colors[[r, g, b, a]] = true
+        alpha ||= a < 255
+      end
+      { width: image.width, height: image.height, format: image.metadata.fetch("format", "RGBA"), colors: colors.length,
+        alpha: alpha, metadata: image.metadata.dup }
+    end
+
+    def resize(image, geometry, filter: :lanczos3, gravity: :center)
+      geometry = Geometry.parse(geometry) unless geometry.is_a?(Geometry)
+      width, height = geometry.target_size(image.width, image.height)
+      output = resample(image, width, height, filter)
+      if geometry.mode == :cover && geometry.width && geometry.height
+        crop_width, crop_height = geometry.crop_size(image.width, image.height)
+        x, y = Gravity.offset(output.width, output.height, crop_width, crop_height, gravity)
+        x = geometry.offset_x unless geometry.offset_x.zero?
+        y = geometry.offset_y unless geometry.offset_y.zero?
+        output = output.crop(x.clamp(0, [output.width - crop_width, 0].max), y.clamp(0, [output.height - crop_height, 0].max), crop_width, crop_height)
+      end
+      output
+    end
+
+    def thumbnail(image, geometry, **options)
+      result = resize(image, geometry, **options)
+      Tessel::Image.from_rgba(result.width, result.height, result.bytes)
+    end
+
+    def crop(image, geometry, gravity: :north_west)
+      geometry = Geometry.parse(geometry) unless geometry.is_a?(Geometry)
+      width, height = geometry.crop_size(image.width, image.height)
+      x, y = if geometry.offset_x.zero? && geometry.offset_y.zero?
+               Gravity.offset(image.width, image.height, width, height, gravity)
+             else
+               [geometry.offset_x, geometry.offset_y]
+             end
+      copy_metadata(image.crop(x, y, width, height), image)
+    end
+
+    def flip(image) = image.flip_vertical
+
+    def flop(image)
+      output = Tessel::Image.new(image.width, image.height, metadata: image.metadata)
+      image.height.times do |y|
+        image.width.times { |x| output[image.width - x - 1, y] = image[x, y] }
+      end
+      output
+    end
+
+    def rotate(image, degrees, background: [0, 0, 0, 0])
+      angle = Float(degrees) % 360
+      raise ArgumentError, "degrees must be finite" unless angle.finite?
+
+      return image.dup if angle.zero?
+      return rotate_quarter(image, 1) if angle == 90
+      return rotate_quarter(image, 2) if angle == 180
+      return rotate_quarter(image, 3) if angle == 270
+
+      radians = angle * Math::PI / 180
+      cosine = Math.cos(radians)
+      sine = Math.sin(radians)
+      width = ((image.width * cosine.abs) + (image.height * sine.abs)).ceil
+      height = ((image.width * sine.abs) + (image.height * cosine.abs)).ceil
+      output = Tessel::Image.new(width, height, fill: background, metadata: image.metadata)
+      source_cx = (image.width - 1) / 2.0
+      source_cy = (image.height - 1) / 2.0
+      target_cx = (width - 1) / 2.0
+      target_cy = (height - 1) / 2.0
+      height.times do |y|
+        width.times do |x|
+          dx = x - target_cx
+          dy = y - target_cy
+          sx = (cosine * dx) + (sine * dy) + source_cx
+          sy = (-sine * dx) + (cosine * dy) + source_cy
+          output[x, y] = sample_bilinear(image, sx, sy, background) if sx.between?(0, image.width - 1) && sy.between?(0, image.height - 1)
+        end
+      end
+      output
+    end
+
+    def pad(image, amount, color: [0, 0, 0, 0])
+      amount = Integer(amount)
+      raise ArgumentError, "padding must not be negative" if amount.negative?
+
+      extend(image, image.width + (2 * amount), image.height + (2 * amount), color:, gravity: :center)
+    end
+
+    def extend(image, width, height, color: [0, 0, 0, 0], gravity: :center)
+      width = Integer(width)
+      height = Integer(height)
+      raise ArgumentError, "canvas dimensions must be positive" unless width.positive? && height.positive?
+      raise ArgumentError, "canvas cannot be smaller than image" if width < image.width || height < image.height
+
+      x, y = Gravity.offset(width, height, image.width, image.height, gravity)
+      Tessel::Image.new(width, height, fill: color, metadata: image.metadata).tap { |canvas| canvas.blit(image, x, y) }
+    end
+
+    def border(image, width, color = "#000000")
+      width = Integer(width)
+      raise ArgumentError, "border width must be positive" unless width.positive?
+
+      pad(image, width, color:)
+    end
+
+    def trim(image, color: nil, fuzz: 0)
+      fuzz = Integer(fuzz)
+      raise ArgumentError, "fuzz must be between 0 and 255" unless fuzz.between?(0, 255)
+
+      target = Tessel::Color.pack(color || image[0, 0] || [0, 0, 0, 0]).bytes
+      bounds = [image.width, image.height, -1, -1]
+      image.height.times do |y|
+        image.width.times do |x|
+          pixel = image[x, y]
+          next if pixel.zip(target).all? { |a, b| (a - b).abs <= fuzz }
+
+          bounds[0] = [bounds[0], x].min
+          bounds[1] = [bounds[1], y].min
+          bounds[2] = [bounds[2], x].max
+          bounds[3] = [bounds[3], y].max
+        end
+      end
+      return image.dup if bounds[2].negative?
+
+      copy_metadata(image.crop(bounds[0], bounds[1], bounds[2] - bounds[0] + 1, bounds[3] - bounds[1] + 1), image)
+    end
+
+    def resample(image, width, height, filter)
+      filter = filter.to_sym
+      raise ArgumentError, "unknown resize filter: #{filter}" unless %i[nearest bilinear bicubic lanczos3].include?(filter)
+      return image.scale_nearest(width, height) if filter == :nearest
+
+      horizontal = axis_weights(image.width, width, filter)
+      vertical = axis_weights(image.height, height, filter)
+      source = image.bytes
+      intermediate = String.new(capacity: width * image.height * 4, encoding: Encoding::BINARY)
+      image.height.times do |y|
+        width.times do |x|
+          sums = [0.0, 0.0, 0.0, 0.0]
+          horizontal[x].each do |sx, weight|
+            offset = ((y * image.width) + sx) * 4
+            alpha = source.getbyte(offset + 3) / 255.0
+            sums[0] += source.getbyte(offset) * alpha * weight
+            sums[1] += source.getbyte(offset + 1) * alpha * weight
+            sums[2] += source.getbyte(offset + 2) * alpha * weight
+            sums[3] += source.getbyte(offset + 3) * weight
+          end
+          sums.each { |value| intermediate << value.round.clamp(0, 255) }
+        end
+      end
+      result = String.new(capacity: width * height * 4, encoding: Encoding::BINARY)
+      height.times do |y|
+        width.times do |x|
+          sums = [0.0, 0.0, 0.0, 0.0]
+          vertical[y].each do |sy, weight|
+            offset = ((sy * width) + x) * 4
+            4.times { |channel| sums[channel] += intermediate.getbyte(offset + channel) * weight }
+          end
+          alpha = sums[3].round.clamp(0, 255)
+          if alpha.positive?
+            3.times { |channel| result << (sums[channel] * 255 / alpha).round.clamp(0, 255) }
+          else
+            result << "\0\0\0".b
+          end
+          result << alpha
+        end
+      end
+      Tessel::Image.from_rgba(width, height, result, metadata: image.metadata)
+    end
+
+    def axis_weights(source, target, filter)
+      radius = { bilinear: 1, bicubic: 2, lanczos3: 3 }.fetch(filter)
+      scale = [source.to_f / target, 1.0].max
+      (0...target).map do |out|
+        center = ((out + 0.5) * source / target) - 0.5
+        first = (center - (radius * scale)).floor
+        last = (center + (radius * scale)).ceil
+        weights = Hash.new(0.0)
+        (first..last).each do |index|
+          distance = (center - index) / scale
+          weight = case filter
+                   when :bilinear then [1 - distance.abs, 0].max
+                   when :bicubic then cubic(distance)
+                   when :lanczos3 then lanczos(distance)
+                   end
+          weights[index.clamp(0, source - 1)] += weight
+        end
+        total = weights.values.sum
+        weights.map { |index, weight| [index, weight / total] }
+      end
+    end
+
+    def cubic(value)
+      value = value.abs
+      return (((1.5 * value) - 2.5) * value * value) + 1 if value < 1
+      return (((((-0.5 * value) + 2.5) * value) - 4) * value) + 2 if value < 2
+
+      0.0
+    end
+
+    def lanczos(value)
+      value = value.abs
+      return 1.0 if value.zero?
+      return 0.0 if value >= 3
+
+      Math.sin(Math::PI * value) * Math.sin(Math::PI * value / 3) * 3 / (Math::PI * Math::PI * value * value)
+    end
+
+    def copy_metadata(output, source)
+      Tessel::Image.from_rgba(output.width, output.height, output.bytes, metadata: source.metadata)
+    end
+
+    def rotate_quarter(image, turns)
+      width, height = turns.odd? ? [image.height, image.width] : [image.width, image.height]
+      output = Tessel::Image.new(width, height, metadata: image.metadata)
+      image.height.times do |y|
+        image.width.times do |x|
+          dx, dy = case turns
+                   when 1 then [image.height - y - 1, x]
+                   when 2 then [image.width - x - 1, image.height - y - 1]
+                   else [y, image.width - x - 1]
+                   end
+          output[dx, dy] = image[x, y]
+        end
+      end
+      copy_metadata(output, image)
+    end
+
+    def sample_bilinear(image, x, y, background)
+      x0 = x.floor
+      y0 = y.floor
+      fx = x - x0
+      fy = y - y0
+      pixels = [[x0, y0, (1 - fx) * (1 - fy)], [x0 + 1, y0, fx * (1 - fy)], [x0, y0 + 1, (1 - fx) * fy], [x0 + 1, y0 + 1, fx * fy]]
+      sums = [0.0, 0.0, 0.0, 0.0]
+      pixels.each do |px, py, weight|
+        color = image[px.clamp(0, image.width - 1), py.clamp(0, image.height - 1)] || Tessel::Color.pack(background).bytes
+        alpha = color[3] / 255.0
+        3.times { |channel| sums[channel] += color[channel] * alpha * weight }
+        sums[3] += color[3] * weight
+      end
+      alpha = sums[3].round.clamp(0, 255)
+      [*(alpha.positive? ? sums.first(3).map { |value| (value * 255 / alpha).round.clamp(0, 255) } : [0, 0, 0]), alpha]
+    end
+
+    private_class_method :resample, :axis_weights, :cubic, :lanczos, :copy_metadata, :rotate_quarter, :sample_bilinear
+  end
+end

data/lib/retouch/pipeline.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Retouch
+  class Pipeline
+    OPERATIONS = %i[resize thumbnail crop flip flop rotate pad extend border trim].freeze
+
+    def initialize(image, operations = [])
+      raise TypeError, "image must be a Tessel::Image" unless image.is_a?(Tessel::Image)
+
+      @source = image.dup
+      @operations = operations.freeze
+    end
+
+    def to_image
+      @operations.reduce(@source.dup) do |image, (name, args, options)|
+        args = args.dup
+        Operations.apply(image, name, *args, **options)
+      end
+    end
+
+    def info = Operations.info(to_image)
+
+    def save(path, **options)
+      ImageIO.write(to_image, String(path), **options)
+    end
+
+    def method_missing(name, *args, **options, &block)
+      return super if block || !OPERATIONS.include?(name)
+
+      self.class.new(@source, @operations + [[name, args, options]])
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      OPERATIONS.include?(name) || super
+    end
+  end
+end

data/lib/retouch/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Retouch
+  VERSION = "0.1.0"
+end

data/lib/retouch.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "tessel"
+require "fileutils"
+require_relative "retouch/version"
+require_relative "retouch/geometry"
+require_relative "retouch/gravity"
+require_relative "retouch/operations"
+require_relative "retouch/pipeline"
+require_relative "retouch/cli"
+require_relative "retouch/io"
+
+module Retouch
+  class Error < StandardError; end
+
+  def self.open(path)
+    Pipeline.new(ImageIO.read(path))
+  end
+
+  def self.from_image(image)
+    Pipeline.new(image)
+  end
+end

data/retouch.gemspec

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "lib/retouch/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "retouch"
+  spec.version = Retouch::VERSION
+  spec.authors = ["Yudai Takada"]
+  spec.email = ["t.yudai92@gmail.com"]
+  spec.summary = "Ruby image resizing and shape tools"
+  spec.description = "A small Ruby image editor and command line tool for resizing and shape operations."
+  spec.homepage = "https://github.com/rbgfx/retouch"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.1.0"
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "#{spec.homepage}/tree/main"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = IO.popen(%w[git ls-files -z], chdir: __dir__, err: IO::NULL) do |ls|
+    ls.readlines("\x0", chomp: true).reject do |file|
+      file.start_with?(*%w[bin/ Gemfile .gitignore .rspec spec/ test/ .github/]) || file == "Gemfile.lock"
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = ["retouch"]
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "tessel", ">= 0.2.0", "< 1"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rbs", "~> 3.0"
+  spec.add_development_dependency "rubocop", "~> 1.0"
+  spec.add_development_dependency "simplecov", "~> 0.22"
+  spec.add_development_dependency "test-unit", "~> 3.6"
+end

data/sig/retouch.rbs

@@ -0,0 +1,45 @@
+module Retouch
+  VERSION: String
+
+  class Error < StandardError
+  end
+
+  class Geometry
+    attr_reader width: Integer | Float | nil
+    attr_reader height: Integer | Float | nil
+    attr_reader offset_x: Integer
+    attr_reader offset_y: Integer
+    attr_reader mode: Symbol
+
+    def self.parse: (String value) -> Geometry
+    def crop_size: (Integer source_width, Integer source_height) -> [Integer, Integer]
+    def target_size: (Integer source_width, Integer source_height) -> [Integer, Integer]
+  end
+
+  module Gravity
+    def self.offset: (Integer container_width, Integer container_height, Integer content_width, Integer content_height, Symbol | String gravity) -> [Integer, Integer]
+  end
+
+  class Pipeline
+    def to_image: -> untyped
+    def info: -> Hash[Symbol, untyped]
+    def save: (String path, ?level: Integer, ?strip: bool) -> String
+    def resize: (String | Geometry geometry, **untyped options) -> Pipeline
+    def thumbnail: (String | Geometry geometry, **untyped options) -> Pipeline
+    def crop: (String | Geometry geometry, **untyped options) -> Pipeline
+    def flip: -> Pipeline
+    def flop: -> Pipeline
+    def rotate: (Numeric degrees, **untyped options) -> Pipeline
+    def pad: (Integer amount, **untyped options) -> Pipeline
+    def extend: (Integer width, Integer height, **untyped options) -> Pipeline
+    def border: (Integer width, ?String color, **untyped options) -> Pipeline
+    def trim: (**untyped options) -> Pipeline
+  end
+
+  def self.open: (String path) -> Pipeline
+  def self.from_image: (untyped image) -> Pipeline
+
+  class CLI
+    def self.run: (Array[String] argv, ?out: untyped, ?err: untyped) -> Integer
+  end
+end

metadata

@@ -0,0 +1,152 @@
+--- !ruby/object:Gem::Specification
+name: retouch
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Yudai Takada
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: tessel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rbs
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: test-unit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+description: A small Ruby image editor and command line tool for resizing and shape
+  operations.
+email:
+- t.yudai92@gmail.com
+executables:
+- retouch
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- CHANGELOG.md
+- LICENSE
+- README.md
+- Rakefile
+- bench/retouch.rb
+- exe/retouch
+- lib/retouch.rb
+- lib/retouch/cli.rb
+- lib/retouch/geometry.rb
+- lib/retouch/gravity.rb
+- lib/retouch/io.rb
+- lib/retouch/operations.rb
+- lib/retouch/pipeline.rb
+- lib/retouch/version.rb
+- retouch.gemspec
+- sig/retouch.rbs
+homepage: https://github.com/rbgfx/retouch
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/rbgfx/retouch
+  source_code_uri: https://github.com/rbgfx/retouch/tree/main
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Ruby image resizing and shape tools
+test_files: []