retouch 0.1.0 → 0.3.0

checksums.yaml

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

data/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All notable changes to Retouch are recorded here.
 
-## [0.1.0] - 2026-09-25
+## [0.3.0] - 2026-09-25
 
-Initial release
+### Added
+
+- Pure Ruby PNG, PPM, and BMP editing through lazy pipelines and a command line.
+- Geometry-based resampling, color adjustments, filters, drawing, compositing, and batch tools.
+- Optional Flipbook, Glyphic, and Lookalike integrations.

data/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2026 Yudai Takada
+Copyright (c) 2026 ydah
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,56 +1,103 @@
-<h1 align="center">Retouch</h1>
+<div align="center">
 
-<p align="center">Resize and reshape images with a small Ruby API and CLI.</p>
+# Retouch
 
-<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>
+Small Ruby image edits, from the terminal or a Ruby pipeline.
 
-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.
+[![CI](https://github.com/rbgfx/retouch/actions/workflows/main.yml/badge.svg)](https://github.com/rbgfx/retouch/actions/workflows/main.yml)
+[![Gem](https://img.shields.io/gem/v/retouch)](https://rubygems.org/gems/retouch)
+
+</div>
+
+Retouch handles everyday image cleanup without an ImageMagick install. It reads and writes PNG, PPM, and BMP through [Tessel](https://github.com/rbgfx/tessel). GIF input and GIF/APNG output, text rendering, and image diffs are available through optional [Flipbook](https://github.com/rbgfx/flipbook), [Glyphic](https://github.com/rbgfx/glyphic), and [Lookalike](https://github.com/rbgfx/lookalike) gems.
+
+JPEG, WebP, color profiles, and very large photographic workloads are outside the current scope.
 
 ## Install
 
-Until the first RubyGems release, add the repository to your Gemfile:
+~~~sh
+gem install retouch
+~~~
 
-```ruby
-gem "retouch", github: "rbgfx/retouch"
-```
+Install optional integrations only when needed:
 
-## Ruby API
+~~~sh
+gem install flipbook glyphic lookalike
+~~~
 
-```ruby
+## CLI
+
+~~~sh
+retouch info screenshot.png
+retouch screenshot.png resize 50% border 2 '#303846' -o small.png
+retouch screenshot.png crop 800x600+120+40 text 'v1.2' --at south-east --font ./font.ttf -o crop.png
+retouch sprite.png resize 400% --filter nearest -o sprite@4x.png
+retouch 'shots/*.png' thumbnail 320x -o 'thumbs/{name}.png'
+retouch 'frames/*.png' animate --fps 24 -o animation.gif
+retouch a.png b.png c.png montage --cols 3 --gap 8 -o sheet.png
+retouch diff expected.png actual.png -o diff.png
+~~~
+
+Resize geometry follows familiar ImageMagick-style notation, with intentionally limited semantics:
+
+| Geometry | Result |
+| --- | --- |
+| 800x600 | Fit inside while preserving aspect ratio |
+| 800x600! | Stretch to the exact dimensions |
+| 800x600^ | Scale to cover, then crop |
+| 800x / x600 | Set one dimension and preserve aspect ratio |
+| 50% / 50%x25% | Scale relative to source size |
+| 800x600> | Shrink only |
+| 800x600+10+20 | Dimensions plus crop offset |
+
+Supported resize filters are nearest, bilinear, bicubic, and lanczos3 (default). A crop without offsets starts at the top left; --gravity selects one of nine anchors for crop, cover, overlay, and text.
+
+Use --dry-run, --verbose, --quiet, --force, --strip, --level 0..9, and --jobs N to control batch runs. Batch templates accept {name}, {ext}, {dir}, {index}, and {index:03}. Existing output files are preserved unless --force is used; conflicting templates fail before processing.
+
+## Ruby
+
+~~~ruby
 require "retouch"
 
 Retouch.open("screenshot.png")
-  .resize("640x")
-  .border(1, "#303846")
+  .resize("50%")
+  .border(2, "#303846")
   .save("small.png")
-```
 
-Pipelines defer work until `to_image` or `save` and leave the source image unchanged.
+image = Retouch.open("screenshot.png")
+  .crop("800x600+120+40")
+  .grayscale
+  .to_image
 
-## CLI
+Retouch.batch("shots/*.png", to: "thumbs/{name}.png") do |image|
+  image.thumbnail("320x")
+end
+~~~
 
-```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
-```
+Pipelines defer work until to_image or save and never mutate the source image. Available operations are resize/thumbnail/crop, flip/flop/rotate, trim/pad/extend/border, grayscale/invert/brightness/contrast/gamma/saturate/tint/opacity/quantize, blur/sharpen/pixelate, overlay/watermark/text/rect/arrow, and multi-image montage/append/spritesheet/animate/diff.
+
+Text requires a BDF or TrueType font path (font: or RETOUCH_FONT). Without Glyphic, only text reports a missing optional dependency. GIF/APNG and perceptual diff operations similarly report their optional gem when invoked.
+
+Pure Ruby pixel processing trades speed for easy installation. Nearest-neighbor scaling is suitable for pixel art; Lanczos, blur, and arbitrary-angle rotation cost more as image dimensions grow. Retouch does not claim ImageMagick pixel-for-pixel compatibility.
 
-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`.
+On Ruby 4.0.6 with YJIT, a local run on a solid 1920×1080 image measured bilinear resize to 960×540 at 1.236s, Lanczos3 at 2.238s, Gaussian blur at σ=3 at 13.423s, and brightness at 0.184s. Nearest-neighbor enlargement from 256×256 to 1024×1024 took 0.071s. Treat these as reference measurements, not guarantees; Gaussian blur is currently the slow path and exceeds the design target of 3 seconds.
 
-Outputs are protected from accidental overwrite; use `--force` to replace one. `--dry-run`, `--verbose`, `--quiet`, `--strip`, and `--level 0..9` control a command.
+## API contracts
+
+Inputs are file paths or Tessel::Image values with RGBA8 pixels. Transformations return a new image and leave the input untouched. Geometry, option, and frame errors raise ArgumentError; values of the wrong type raise TypeError; I/O and unavailable optional integrations raise Retouch::Error. Pipeline#save overwrites its destination, while the CLI and Retouch.batch refuse existing outputs unless --force / force: true is supplied.
+
+Retouch supports PNG, PPM, and BMP input/output. GIF input and GIF/APNG output need Flipbook; text and montage labels need Glyphic and a BDF/TrueType font; diff needs Lookalike. JPEG, WebP, color management, and APNG input are unsupported. Pipelines are safe to reuse from independent calls; Tessel image mutability follows Tessel's contract, and --jobs uses processes where fork exists.
 
 ## Development
 
-```sh
+~~~sh
 bundle install
 bundle exec rake verify
-```
+COVERAGE=1 COVERAGE_MIN=85 bundle exec rake test
+~~~
+
+The verification task runs RuboCop, test-unit, and RBS validation. The README Ruby examples are exercised by the test suite.
 
 ## License
 
-MIT. See [LICENSE](LICENSE).
+MIT

data/bench/retouch.rb

@@ -13,7 +13,8 @@ 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("1920x1080 blur sigma=3") { Retouch::Operations.blur(image, sigma: 3) }
+measure("1920x1080 brightness") { Retouch::Operations.brightness(image, 0.1) }
 measure("256x256 -> 1024x1024 nearest") do
   Retouch::Operations.resize(Tessel::Image.new(256, 256), "400%", filter: :nearest)
 end

data/lib/retouch/batch.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Retouch
+  module Batch
+    module_function
+
+    def run(pattern, to:, force: false, jobs: 1, level: 6, strip: false, &operation)
+      raise ArgumentError, "a block is required" unless operation
+
+      files = Array(pattern).flat_map { |item| File.file?(item) ? [item] : Dir.glob(item) }.uniq.sort
+      raise Error, "no input files matched" if files.empty?
+
+      jobs = Integer(jobs)
+      raise ArgumentError, "jobs must be positive" unless jobs.positive?
+
+      outputs = files.each_with_index.map { |file, index| expand(to, file, index) }
+      raise ArgumentError, "output template maps multiple inputs to the same file" unless outputs.uniq.length == outputs.length
+      raise Error, "refusing to overwrite #{outputs.find { |path| File.exist?(path) }}" unless force || outputs.none? { |path| File.exist?(path) }
+
+      work = files.zip(outputs).map { |input, output| [input, output] }
+      return work.map { |input, output| process(input, output, level:, strip:, &operation) } if jobs == 1 || !Process.respond_to?(:fork)
+
+      work.each_slice(jobs).flat_map do |group|
+        children = group.map do |input, output|
+          pid = Process.fork do
+            process(input, output, level:, strip:, &operation)
+            exit! 0
+          rescue StandardError
+            exit! 1
+          end
+          [pid, output]
+        end
+        children.each do |pid, output|
+          _, status = Process.wait2(pid)
+          raise Error, "batch worker failed for #{output}" unless status.success?
+        end
+        group.map(&:last)
+      end
+    end
+
+    def expand(template, path, index)
+      template = String(template)
+      name = File.basename(path, File.extname(path))
+      values = { "name" => name, "ext" => File.extname(path).delete_prefix("."), "dir" => File.dirname(path), "index" => index.to_s }
+      template.gsub(/\{(name|ext|dir|index)(?::(\d+))?\}/) do
+        key, width = Regexp.last_match.captures
+        value = values.fetch(key)
+        key == "index" && width ? value.rjust(width.to_i, "0") : value
+      end
+    end
+
+    def process(input, output, level:, strip:)
+      result = yield Retouch.open(input)
+      result = Retouch.from_image(result) if result.is_a?(Tessel::Image)
+      raise TypeError, "batch block must return a Retouch::Pipeline" unless result.is_a?(Pipeline)
+
+      FileUtils.mkdir_p(File.dirname(output)) unless File.dirname(output) == "."
+      result.save(output, level:, strip:)
+      output
+    end
+  end
+end

data/lib/retouch/cli.rb

@@ -5,7 +5,11 @@ require "optparse"
 
 module Retouch
   class CLI
-    OPERATIONS = %w[resize thumbnail crop flip flop rotate pad extend border trim].freeze
+    OPERATIONS = %w[
+      info resize thumbnail crop flip flop rotate pad extend border trim grayscale invert brightness
+      contrast gamma saturate tint opacity quantize blur sharpen pixelate overlay watermark text rect
+      arrow montage append spritesheet animate diff
+    ].freeze
 
     def self.run(argv, out: $stdout, err: $stderr)
       new(argv, out:, err:).run
@@ -18,39 +22,39 @@ module Retouch
       @args = argv.dup
       @out = out
       @err = err
-      @options = { level: 6 }
+      @pid = Process.pid
+      @options = { jobs: 1, level: 6, frame: 0 }
       read_global_options
       raise ArgumentError, "PNG level must be between 0 and 9" unless @options[:level].between?(0, 9)
+      raise ArgumentError, "jobs must be positive" unless @options[:jobs].positive?
+      raise ArgumentError, "frame must not be negative" if @options[:frame].negative?
     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"
+
+      if @args.first == "info"
+        @args.shift
+        return info_command
+      end
+      if @args.first == "help"
+        @args.shift
+        return help(@args.shift)
+      end
+      return diff_command if @args.first == "diff"
 
       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
+      inputs = expand_inputs(@args.shift(operation_at))
       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]
+      return fail_usage("at least one input is required") if inputs.empty?
+      return aggregate(inputs, operations) if %w[montage append animate spritesheet].include?(operations.first&.first)
 
-      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
+      transform(inputs, operations)
+    rescue ArgumentError, OptionParser::ParseError => e
+      @err.puts("retouch: #{e.message}")
+      2
     rescue StandardError => e
       @err.puts("retouch: #{e.message}")
       @err.puts(e.backtrace.first) if @options[:verbose]
@@ -71,7 +75,9 @@ module Retouch
         when "--quiet" then @options[:quiet] = true
         when "--force" then @options[:force] = true
         when "--strip" then @options[:strip] = true
+        when "--jobs" then @options[:jobs] = Integer(require_value(token))
         when "--level" then @options[:level] = Integer(require_value(token))
+        when "--frame" then @options[:frame] = Integer(require_value(token))
         else remaining << token
         end
       end
@@ -85,6 +91,10 @@ module Retouch
       value
     end
 
+    def expand_inputs(inputs)
+      inputs.flat_map { |item| File.file?(item) ? [item] : Dir.glob(item) }.uniq.sort
+    end
+
     def parse_operations(tokens)
       operations = []
       until tokens.empty?
@@ -92,32 +102,58 @@ module Retouch
         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 "resize", "thumbnail", "crop" then parse_geometry_options(tokens)
+                        when "rotate", "pad", "brightness", "contrast", "gamma", "saturate", "opacity", "pixelate", "tint" then [[required(tokens, name)], {}]
+                        when "extend" then [[required(tokens, name), required(tokens, name)], {}]
                         when "border" then [[required(tokens, name), tokens.first&.start_with?("#") ? tokens.shift : "#000000"], {}]
+                        when "quantize" then [[], read_options(tokens, colors: :integer, dither: :symbol)]
+                        when "blur" then [[], read_options(tokens, sigma: :float)]
+                        when "sharpen" then [[], read_options(tokens, amount: :float, sigma: :float)]
+                        when "text" then [[required(tokens, name)], read_options(tokens, at: :symbol, size: :integer, color: :string, font: :string, background: :string, padding: :integer)]
+                        when "rect" then [[required(tokens, name)], read_options(tokens, color: :string, fill: :boolean, width: :integer)]
+                        when "arrow" then [[required(tokens, name), required(tokens, name), required(tokens, name), required(tokens, name)], read_options(tokens, color: :string, width: :float, head: :float)]
+                        when "overlay", "watermark" then [[required(tokens, name)], read_options(tokens, x: :integer, y: :integer, gravity: :symbol, opacity: :float, blend: :symbol)]
+                        when "montage" then [[], read_options(tokens, cols: :integer, gap: :integer, background: :string, label: :boolean, font: :string)]
+                        when "append" then [[], read_options(tokens, direction: :symbol, gap: :integer, background: :string)]
+                        when "spritesheet" then [[], read_options(tokens, cols: :integer, gap: :integer, background: :string)]
+                        when "animate" then [[], read_options(tokens, fps: :float, delay: :float, loop: :boolean)]
                         when "trim" then [[], read_options(tokens, fuzz: :integer, color: :string)]
-                        when "flip", "flop" then [[], {}]
+                        when "info", "flip", "flop", "grayscale", "invert" then [[], {}]
+                        else raise ArgumentError, "#{name} cannot be used in a pipeline"
                         end
         operations << [name, args, options]
       end
       operations
     end
 
+    def parse_geometry_options(tokens)
+      geometry = required(tokens, "geometry")
+      options = read_options(tokens, filter: :symbol, gravity: :symbol, fuzz: :integer, color: :string)
+      [[geometry], options]
+    end
+
     def read_options(tokens, specification)
       options = {}
-      while tokens.first&.start_with?("--")
-        option = tokens.shift.delete_prefix("--").tr("-", "_").to_sym
+      loop do
+        break unless tokens.first&.start_with?("--")
+
+        token = tokens.shift.delete_prefix("--")
+        disabled = token.start_with?("no-")
+        option = token.delete_prefix("no-").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
+        if type == :boolean
+          options[option] = !disabled
+        else
+          value = required(tokens, option)
+          options[option] = case type
+                            when :integer then Integer(value)
+                            when :float then Float(value)
+                            when :symbol then value.tr("-", "_").to_sym
+                            else value
+                            end
+        end
       end
       options
     end
@@ -130,45 +166,168 @@ module Retouch
     end
 
     def info_command
+      files = expand_inputs(@args)
+      return fail_usage("info needs an input file") if files.empty?
+
+      files.each { |path| announce(JSON.pretty_generate(path: path, **Operations.info(ImageIO.read(path, frame: @options[:frame])))) }
+      0
+    end
+
+    def diff_command
       @args.shift
-      return fail_usage("info expects one input file") unless @args.one?
+      files = expand_inputs(@args)
+      raise OptionParser::MissingArgument, "diff expects two image paths" unless files.length == 2
+
+      output = @options[:output] || "diff.png"
+      return announce("retouch diff #{files.join(" ")} -o #{output}") if @options[:dry_run]
 
-      path = @args.first
-      announce(JSON.pretty_generate({ path:, **Operations.info(ImageIO.read(path)) }))
+      image = Operations.diff(ImageIO.read(files[0]), ImageIO.read(files[1]))
+      prepare_output(output)
+      ImageIO.write(image, output, level: @options[:level], strip: @options[:strip])
+      announce(format("diff %<ratio>.2f%% (%<pixels>s pixels)", ratio: image.metadata.fetch("diff_ratio").to_f * 100, pixels: image.metadata.fetch("diff_pixels")))
+      announce(output)
       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
+    def aggregate(files, operations)
+      raise ArgumentError, "aggregate commands cannot be chained" unless operations.length == 1
+
+      operation = operations.first
+      name, _args, options = operation
+      images = files.map { |path| ImageIO.read(path, frame: @options[:frame]) }
+      case name
+      when "montage", "append"
+        options[:labels] = files.map { |path| File.basename(path) } if name == "montage" && options[:label]
+        result = Operations.public_send(name, images, **options)
+        write(result)
+      when "spritesheet"
+        result, map = Operations.spritesheet(images, **options)
+        output = @options[:output] || "spritesheet.png"
+        return announce("retouch spritesheet #{files.length} images -o #{output}") if @options[:dry_run]
+
+        prepare_output(output, sidecars: [output.sub(/\.[^.]+\z/, ".json")])
+        ImageIO.write(result, output, level: @options[:level], strip: @options[:strip])
+        File.write(output.sub(/\.[^.]+\z/, ".json"), JSON.pretty_generate(map))
+        announce(output)
+        0
+      when "animate"
+        output = @options[:output] || "animation.gif"
+        return announce("retouch animate #{files.length} frames -o #{output}") if @options[:dry_run]
+
+        prepare_output(output)
+        Operations.animate(images, output, **options)
+        announce(output)
+        0
+      end
+    end
+
+    def transform(files, operations)
+      return fail_usage("an output path with -o is required") unless @options[:output]
+
+      if files.length > 1
+        outputs = files.map.with_index { |file, index| Batch.expand(@options[:output], file, index) }
+        collision = outputs.group_by(&:itself).find { |_, same| same.length > 1 }
+        raise ArgumentError, "output template collision: #{collision.first}" if collision
+        raise Error, "refusing to overwrite output; use --force" if !@options[:force] && outputs.any? { |path| File.exist?(path) }
+        return 0 if @options[:dry_run] && files.zip(outputs).each { |input, output| announce("#{output} <= #{input}") }
+
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        outputs = Batch.run(files, to: @options[:output], force: @options[:force], jobs: @options[:jobs], level: @options[:level], strip: @options[:strip]) do |pipeline|
+          pipeline = apply_operations(pipeline, operations)
+          pipeline
+        end
+        elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+        announce(format("batch completed in %<elapsed>.3fs", elapsed:)) if @options[:verbose]
+        outputs.each { |path| announce(path) }
+        return 0
+      end
+      input = files.first
+      output = Batch.expand(@options[:output], input, 0)
+      return announce("retouch #{input} #{operations.map(&:first).join(" ")} -o #{@options[:output]}") if @options[:dry_run]
+      raise Error, "refusing to overwrite #{output}; use --force" if File.exist?(output) && !@options[:force]
+
+      FileUtils.mkdir_p(File.dirname(output)) unless File.dirname(output) == "."
+
+      pipeline = Retouch.open(input, frame: @options[:frame])
+      pipeline = apply_operations(pipeline, operations)
+      pipeline.save(output, level: @options[:level], strip: @options[:strip])
+      announce(output)
+      0
+    end
+
+    def write(image)
+      output = @options[:output] || "retouch.png"
+      return announce("retouch #{output}") if @options[:dry_run]
+
+      prepare_output(output)
+      ImageIO.write(image, output, level: @options[:level], strip: @options[:strip])
+      announce(output)
+      0
     end
 
     def announce(message)
-      @out.puts(message) unless @options[:quiet]
+      @out.puts(message) unless @options[:quiet] || Process.pid != @pid
       0
     end
 
+    def apply_operations(pipeline, operations)
+      image = pipeline.to_image
+      operations.each do |name, args, options|
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        args = args.dup
+        args[0] = ImageIO.read(args[0]) if %w[overlay watermark].include?(name) && args[0].is_a?(String)
+        image = Operations.apply(image, name, *args, **options)
+        elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+        announce(format("%<name>s completed in %<elapsed>.3fs", name:, elapsed:)) if @options[:verbose]
+      end
+      Retouch.from_image(image)
+    end
+
+    def prepare_output(path, sidecars: [])
+      paths = [path, *sidecars]
+      existing = paths.find { |candidate| File.exist?(candidate) }
+      raise Error, "refusing to overwrite #{existing}; use --force" if existing && !@options[:force]
+
+      FileUtils.mkdir_p(File.dirname(path)) unless File.dirname(path) == "."
+    end
+
+    def fail_usage(message)
+      @err.puts("retouch: #{message}")
+      @err.puts("Run 'retouch --help' for usage.")
+      2
+    end
+
     def help(operation = nil)
       if operation
-        raise ArgumentError, "unknown operation help: #{operation}" unless OPERATIONS.include?(operation)
+        details = {
+          "resize" => "retouch INPUT resize GEOMETRY [--filter nearest|bilinear|bicubic|lanczos3] [--gravity POSITION] -o OUTPUT",
+          "crop" => "retouch INPUT crop GEOMETRY [--gravity POSITION] -o OUTPUT",
+          "rotate" => "retouch INPUT rotate DEGREES -o OUTPUT",
+          "border" => "retouch INPUT border WIDTH [#RRGGBB] -o OUTPUT",
+          "blur" => "retouch INPUT blur [--sigma VALUE] -o OUTPUT",
+          "text" => "retouch INPUT text TEXT --font FONT [--at POSITION] [--size PX] -o OUTPUT",
+          "montage" => "retouch INPUT... montage [--cols N] [--gap PX] [--label --font FONT] -o OUTPUT",
+          "spritesheet" => "retouch INPUT... spritesheet [--cols N] [--gap PX] -o OUTPUT"
+        }
+        raise ArgumentError, "unknown operation help: #{operation}" unless OPERATIONS.include?(operation) || details.key?(operation)
 
-        @out.puts("retouch INPUT #{operation} [ARGUMENTS] -o OUTPUT")
+        @out.puts(details.fetch(operation, "retouch INPUT #{operation} [OPTIONS] -o OUTPUT"))
         return 0
       end
       @out.puts <<~HELP
-        Retouch resizes and reshapes PNG, PPM, and BMP images.
+        Retouch edits PNG, PPM, and BMP images; optional integrations add GIF/APNG, text, and visual diffs.
 
-        Usage: retouch INPUT OPERATION [ARGUMENTS] -o OUTPUT
+        Usage: retouch INPUT... OPERATION [ARGUMENTS] -o OUTPUT
                retouch help OPERATION
-               retouch info INPUT
+               retouch info INPUT...
+               retouch diff EXPECTED ACTUAL -o OUTPUT
+
+        Operations: resize thumbnail crop rotate flip flop border trim grayscale invert
+          brightness contrast gamma saturate tint opacity quantize blur sharpen pixelate
+          overlay watermark text rect arrow montage append spritesheet animate
 
-        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
+        Global options: -o, --output PATH  --force  --dry-run  --verbose  --quiet
+                        --strip  --level 0..9  --jobs N  --frame N  -h, --help
       HELP
       0
     end

data/lib/retouch/io.rb

@@ -4,8 +4,17 @@ module Retouch
   module ImageIO
     module_function
 
-    def read(path)
+    def read(path, frame: 0)
+      frame = Integer(frame)
+      raise ArgumentError, "frame must not be negative" if frame.negative?
+
       signature = File.binread(path, 8)
+      if signature.start_with?("GIF87a", "GIF89a")
+        require_optional("flipbook", "GIF input") { require "flipbook" }
+        frames = Flipbook.read(path)
+        image = frames.fetch(frame) { raise ArgumentError, "GIF frame is out of range: #{frame}" }
+        return with_format(image, "GIF")
+      end
       format = if signature.start_with?(Tessel::SIGNATURE)
                  "PNG"
                elsif signature.start_with?("P3", "P6")
@@ -24,6 +33,9 @@ module Retouch
       image = Tessel::Image.from_rgba(image.width, image.height, image.bytes) if strip
       extension = File.extname(path).downcase
       case extension
+      when ".gif", ".apng"
+        require_optional("flipbook", "GIF/APNG output") { require "flipbook" }
+        Flipbook.write(path, [image], format: extension.delete_prefix("."), colors: 256)
       when ".png"
         image.write(path, level: Integer(level))
       when ".ppm", ".pnm"
@@ -38,6 +50,12 @@ module Retouch
       raise Error, e.message, cause: e
     end
 
+    def require_optional(gem, feature)
+      yield
+    rescue LoadError => e
+      raise Error, "#{feature} requires the #{gem} gem", 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:)