retouch 0.3.0 → 0.3.1

data/lib/retouch/cli.rb

@@ -6,10 +6,42 @@ require "optparse"
 module Retouch
   class CLI
     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
+      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
+    MULTI_IMAGE_OPERATIONS = %w[montage append spritesheet animate diff].freeze
+    OPERATION_USAGE = {
+      "resize" => "GEOMETRY [--filter nearest|bilinear|bicubic|lanczos3] [--gravity POSITION]",
+      "thumbnail" => "GEOMETRY [--filter FILTER]",
+      "crop" => "GEOMETRY [--gravity POSITION]",
+      "rotate" => "DEGREES [--background COLOR]",
+      "pad" => "PIXELS [--color COLOR]",
+      "extend" => "WIDTH HEIGHT [--color COLOR] [--gravity POSITION]",
+      "border" => "PIXELS [COLOR]",
+      "trim" => "[--color COLOR] [--fuzz 0..255]",
+      "brightness" => "-255..255",
+      "contrast" => "FACTOR",
+      "gamma" => "GAMMA",
+      "saturate" => "FACTOR",
+      "tint" => "COLOR [--amount 0..1]",
+      "opacity" => "0..1",
+      "quantize" => "[--colors 2..256] [--dither none|ordered|floyd-steinberg]",
+      "blur" => "SIGMA",
+      "sharpen" => "SIGMA [--amount FACTOR]",
+      "pixelate" => "BLOCK_SIZE",
+      "overlay" => "IMAGE [--x X] [--y Y] [--gravity POSITION] [--opacity 0..1] [--mode MODE]",
+      "watermark" => "IMAGE [composite options]",
+      "text" => "TEXT [--at POSITION] [--size PIXELS] [--font FILE] [--background COLOR]",
+      "rect" => "X Y WIDTH HEIGHT [COLOR] [--fill]",
+      "arrow" => "X1 Y1 X2 Y2 [COLOR] [--width PIXELS] [--head PIXELS]",
+      "montage" => "[--cols N] [--gap PIXELS] [--background COLOR] [--label]",
+      "append" => "[--direction vertical|horizontal] [--gap PIXELS]",
+      "spritesheet" => "[--max-width PIXELS] [--gap PIXELS]",
+      "animate" => "(--fps RATE | --delay SECONDS) [--no-loop]",
+      "diff" => "[--threshold 0..255] [--color COLOR]"
+    }.freeze
 
     def self.run(argv, out: $stdout, err: $stderr)
       new(argv, out:, err:).run
@@ -22,39 +54,35 @@ module Retouch
       @args = argv.dup
       @out = out
       @err = err
-      @pid = Process.pid
-      @options = { jobs: 1, level: 6, frame: 0 }
+      @options = { level: 6, jobs: 1, loop: true }
       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?
-
-      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"
+      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 = expand_inputs(@args.shift(operation_at))
-      operations = parse_operations(@args)
-      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)
+      inputs = @args.shift(operation_at)
+      return fail_usage("at least one input file is required") if inputs.empty?
+      return fail_usage("an output path with -o is required") unless @options[:output]
+
+      operation = @args.first
+      parsed = parse_cli_operations(@args)
+      return 2 unless parsed
 
-      transform(inputs, operations)
-    rescue ArgumentError, OptionParser::ParseError => e
-      @err.puts("retouch: #{e.message}")
-      2
+      if MULTI_IMAGE_OPERATIONS.include?(operation)
+        return fail_usage("#{operation} must be the only operation in its command") unless parsed.one?
+
+        multi_image_command(inputs, operation, parsed.fetch(0))
+      else
+        image_command(inputs, parsed)
+      end
     rescue StandardError => e
       @err.puts("retouch: #{e.message}")
       @err.puts(e.backtrace.first) if @options[:verbose]
@@ -75,9 +103,10 @@ 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 "--loop" then @options[:loop] = true
+        when "--no-loop" then @options[:loop] = false
         when "--level" then @options[:level] = Integer(require_value(token))
-        when "--frame" then @options[:frame] = Integer(require_value(token))
+        when "--jobs" then @options[:jobs] = Integer(require_value(token))
         else remaining << token
         end
       end
@@ -91,10 +120,6 @@ 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?
@@ -102,58 +127,68 @@ module Retouch
         raise ArgumentError, "unknown operation: #{name}" unless OPERATIONS.include?(name)
 
         args, options = case name
-                        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 "resize", "thumbnail", "crop"
+                          [[required(tokens, "geometry")], read_options(tokens, filter: :symbol, gravity: :symbol)]
+                        when "rotate" then [[Float(required(tokens, name))], read_options(tokens, background: :color)]
+                        when "pad" then [[Integer(required(tokens, name))], read_options(tokens, color: :color)]
+                        when "extend" then [[Integer(required(tokens, name)), Integer(required(tokens, name))], read_options(tokens, color: :color, gravity: :symbol)]
+                        when "border" then [[Integer(required(tokens, name)), tokens.first&.start_with?("#") ? tokens.shift : "#000000"], {}]
+                        when "trim" then [[], read_options(tokens, fuzz: :integer, color: :color)]
+                        when "brightness", "contrast", "gamma", "saturate", "opacity" then [[Float(required(tokens, name))], {}]
+                        when "tint" then [[required(tokens, "color")], read_options(tokens, amount: :float)]
                         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 "info", "flip", "flop", "grayscale", "invert" then [[], {}]
-                        else raise ArgumentError, "#{name} cannot be used in a pipeline"
+                        when "blur", "sharpen" then [[Float(required(tokens, name))], read_options(tokens, amount: :float)]
+                        when "pixelate" then [[Integer(required(tokens, name))], {}]
+                        when "overlay", "watermark"
+                          [[ImageIO.read(required(tokens, "overlay image"))], read_options(tokens, x: :integer, y: :integer, gravity: :symbol, opacity: :float, mode: :symbol)]
+                        when "text"
+                          [[required(tokens, "text")], read_options(tokens, x: :integer, y: :integer, at: :symbol, size: :integer, font: :string, color: :color, background: :color, padding: :integer)]
+                        when "rect"
+                          [[Integer(required(tokens, "x")), Integer(required(tokens, "y")), Integer(required(tokens, "width")), Integer(required(tokens, "height")), tokens.first&.start_with?("#") ? tokens.shift : "#ffffff"], read_options(tokens, fill: :flag)]
+                        when "arrow"
+                          [[Integer(required(tokens, "x1")), Integer(required(tokens, "y1")), Integer(required(tokens, "x2")), Integer(required(tokens, "y2")), tokens.first&.start_with?("#") ? tokens.shift : "#ffffff"], read_options(tokens, width: :integer, head: :float)]
+                        when "montage" then [[], read_options(tokens, cols: :integer, gap: :integer, background: :color, label: :flag)]
+                        when "append" then [[], read_options(tokens, direction: :symbol, gap: :integer, background: :color)]
+                        when "spritesheet" then [[], read_options(tokens, max_width: :integer, gap: :integer, background: :color)]
+                        when "animate"
+                          options = read_options(tokens, fps: :float, delay: :float, colors: :integer, dither: :symbol)
+                          raise OptionParser::InvalidArgument, "use either --fps or --delay" if options.key?(:fps) && options.key?(:delay)
+                          raise OptionParser::MissingArgument, "--fps or --delay" unless options.key?(:fps) || options.key?(:delay)
+
+                          [[], options]
+                        when "diff" then [[], read_options(tokens, threshold: :float, color: :color)]
+                        when "grayscale", "invert", "flip", "flop" then [[], {}]
                         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]
+    def parse_cli_operations(tokens)
+      parse_operations(tokens)
+    rescue ArgumentError, OptionParser::ParseError => e
+      @err.puts("retouch: #{e.message}")
+      nil
     end
 
     def read_options(tokens, specification)
       options = {}
-      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
+      while tokens.first&.start_with?("--")
+        option = tokens.shift.delete_prefix("--").tr("-", "_").to_sym
         type = specification[option]
         raise OptionParser::InvalidOption, "--#{option}" unless type
 
-        if type == :boolean
-          options[option] = !disabled
-        else
-          value = required(tokens, option)
-          options[option] = case type
+        options[option] = if type == :flag
+                            true
+                          else
+                            value = required(tokens, 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
       end
       options
     end
@@ -165,130 +200,96 @@ module Retouch
       value
     end
 
-    def info_command
-      files = expand_inputs(@args)
-      return fail_usage("info needs an input file") if files.empty?
+    def image_command(inputs, operations)
+      expanded = expand_inputs(inputs)
+      return fail_usage("no input files matched") if expanded.empty?
 
-      files.each { |path| announce(JSON.pretty_generate(path: path, **Operations.info(ImageIO.read(path, frame: @options[:frame])))) }
-      0
-    end
+      batch = expanded.length > 1 || inputs.any? { |input| input.match?(/[?*{\[]/) } || @options[:output].include?("{")
+      if batch
+        return fail_usage("batch output must use a template such as {name}") if expanded.length > 1 && !@options[:output].include?("{")
 
-    def diff_command
-      @args.shift
-      files = expand_inputs(@args)
-      raise OptionParser::MissingArgument, "diff expects two image paths" unless files.length == 2
+        outputs = Batch.run(expanded, to: @options[:output], jobs: @options[:jobs], force: @options[:force], dry_run: @options[:dry_run]) do |input, output|
+          apply_operations(Retouch.open(input), operations).save(output, level: @options[:level], strip: @options[:strip])
+        end
+        outputs.each { |path| announce(path) } if @options[:dry_run] || !@options[:quiet]
+        return 0
+      end
 
-      output = @options[:output] || "diff.png"
-      return announce("retouch diff #{files.join(" ")} -o #{output}") if @options[:dry_run]
+      output = @options[:output]
+      return announce("retouch #{expanded.first} #{operations.map(&:first).join(" ")} -o #{output}") if @options[:dry_run]
+      raise Error, "input file does not exist: #{expanded.first}" unless File.file?(expanded.first)
+      raise Error, "refusing to overwrite #{output}; use --force" if File.exist?(output) && !@options[:force]
 
-      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")))
+      result = apply_operations(Retouch.open(expanded.first), operations)
+      FileUtils.mkdir_p(File.dirname(output)) unless File.dirname(output) == "."
+      result.save(output, level: @options[:level], strip: @options[:strip])
       announce(output)
-      0
     end
 
-    def aggregate(files, operations)
-      raise ArgumentError, "aggregate commands cannot be chained" unless operations.length == 1
+    def multi_image_command(inputs, name, (_operation, _arguments, options))
+      paths = expand_inputs(inputs)
+      return fail_usage("no input files matched") if paths.empty?
+      return fail_usage("#{name} expects at least two images") if paths.length < 2
+      return fail_usage("diff expects exactly two images") if name == "diff" && paths.length != 2
+
+      output = @options[:output]
+      manifest = spritesheet_manifest_path(output) if name == "spritesheet"
+      outputs = name == "spritesheet" ? [output, manifest] : [output]
+      return announce("retouch #{paths.join(" ")} #{name} -o #{output}") if @options[:dry_run]
+      if !@options[:force] && (existing = outputs.find { |path| File.exist?(path) })
+        raise Error, "refusing to overwrite #{existing}; use --force"
+      end
 
-      operation = operations.first
-      name, _args, options = operation
-      images = files.map { |path| ImageIO.read(path, frame: @options[:frame]) }
+      FileUtils.mkdir_p(File.dirname(output)) unless File.dirname(output) == "."
+      images = paths.map { |path| ImageIO.read(path) }
       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 "montage"
+        options[:labels] = paths.map { |path| File.basename(path) } if options.delete(:label)
+        Operations.montage(images, **options).then { |image| ImageIO.write(image, output, level: @options[:level], strip: @options[:strip]) }
+      when "append"
+        Operations.append(images, **options).then { |image| ImageIO.write(image, output, level: @options[:level], strip: @options[:strip]) }
       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
+        image, placements = Operations.spritesheet(images, **options)
+        ImageIO.write(image, output, level: @options[:level], strip: @options[:strip])
+        File.write(manifest, JSON.pretty_generate(placements))
       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
+        Operations.animate(images, output, **options, loop: @options[:loop])
+      when "diff"
+        result = Operations.diff(images[0], images[1], **options)
+        ImageIO.write(result[:image], output, level: @options[:level], strip: @options[:strip])
+        announce(format("%.2f%% pixels differ", result[:rate] * 100))
       end
+      announce(output)
     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
+    def apply_operations(pipeline, operations)
+      operations.reduce(pipeline) do |current, (name, args, options)|
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC) if @options[:verbose]
+        result = current.public_send(name, *args, **options)
+        if started
+          elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+          announce(format("%<operation>s %<elapsed>.3fs", operation: name, elapsed:))
         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
+        result
       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] || Process.pid != @pid
-      0
+    def expand_inputs(inputs)
+      inputs.flat_map do |input|
+        input.match?(/[?*{\[]/) ? Dir.glob(input) : input
+      end
     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)
+    def spritesheet_manifest_path(output)
+      File.extname(output).empty? ? "#{output}.json" : output.sub(%r{\.[^./]+\z}, ".json")
     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]
+    def info_command
+      @args.shift
+      return fail_usage("info expects one input file") unless @args.one?
 
-      FileUtils.mkdir_p(File.dirname(path)) unless File.dirname(path) == "."
+      path = @args.first
+      announce(JSON.pretty_generate({ path:, **Operations.info(ImageIO.read(path)) }))
     end
 
     def fail_usage(message)
@@ -297,37 +298,27 @@ module Retouch
       2
     end
 
+    def announce(message)
+      @out.puts(message) unless @options[:quiet]
+      0
+    end
+
     def help(operation = nil)
       if 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(details.fetch(operation, "retouch INPUT #{operation} [OPTIONS] -o OUTPUT"))
+        raise ArgumentError, "unknown operation help: #{operation}" unless OPERATIONS.include?(operation)
+
+        @out.puts("retouch INPUTS #{operation} #{OPERATION_USAGE.fetch(operation, "")} -o OUTPUT")
         return 0
       end
       @out.puts <<~HELP
-        Retouch edits PNG, PPM, and BMP images; optional integrations add GIF/APNG, text, and visual diffs.
+        Retouch edits PNG, PPM, and BMP images with a Ruby API and CLI.
 
-        Usage: retouch INPUT... OPERATION [ARGUMENTS] -o OUTPUT
+        Usage: retouch INPUT [INPUT ...] OPERATION [ARGUMENTS] -o OUTPUT
+               retouch info INPUT
                retouch help OPERATION
-               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
 
-        Global options: -o, --output PATH  --force  --dry-run  --verbose  --quiet
-                        --strip  --level 0..9  --jobs N  --frame N  -h, --help
+        Operations: #{OPERATIONS.join(" ")}
+        Global: -o PATH --force --dry-run --verbose --quiet --strip --level 0..9 --jobs N --loop --no-loop
       HELP
       0
     end

data/lib/retouch/io.rb

@@ -4,24 +4,19 @@ module Retouch
   module ImageIO
     module_function
 
-    def read(path, frame: 0)
-      frame = Integer(frame)
-      raise ArgumentError, "frame must not be negative" if frame.negative?
-
+    def read(path)
       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")
                  "PPM"
                elsif signature.start_with?("BM")
                  "BMP"
+               elsif signature.start_with?("GIF87a", "GIF89a")
+                 "GIF"
                end
+      return with_format(Operations.open_gif(path, frame: 0), format) if format == "GIF"
+
       with_format(Tessel.read(path), format || "unknown")
     rescue Tessel::UnsupportedError => e
       raise Error, "unsupported image format for #{path}: #{e.message}", cause: e
@@ -33,9 +28,6 @@ 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"
@@ -50,12 +42,6 @@ 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:)

data/lib/retouch/kernels/color.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Retouch
+  module Kernels
+    module_function
+
+    def quantize(image, colors: 256, dither: :none, palette: nil)
+      indices, palette = Tessel::Quantize.quantize(image, colors: Integer(colors), dither: dither.to_sym, palette:)
+      source = image.bytes
+      output = String.new(capacity: source.bytesize, encoding: Encoding::BINARY)
+      (image.width * image.height).times do |index|
+        red, green, blue = palette.fetch(indices.getbyte(index))
+        output << red << green << blue << source.getbyte((index * 4) + 3)
+      end
+      Tessel::Image.from_rgba(image.width, image.height, output, metadata: image.metadata)
+    end
+  end
+end

data/lib/retouch/kernels/convolve.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Retouch
+  module Kernels
+    module Convolve
+      module_function
+
+      def gaussian(image, sigma)
+        sigma = Float(sigma)
+        raise ArgumentError, "sigma must be positive and at most 100" unless sigma.finite? && sigma.positive? && sigma <= 100
+
+        radius = (sigma * 3).ceil
+        weights = (-radius..radius).map { |offset| Math.exp(-(offset * offset) / (2 * sigma * sigma)) }
+        total = weights.sum
+        weights.map! { |weight| weight / total }
+        convolve_axis(convolve_axis(image, weights, horizontal: true), weights, horizontal: false)
+      end
+
+      def convolve_axis(image, weights, horizontal:)
+        width = image.width
+        height = image.height
+        source = image.bytes
+        output = String.new(capacity: source.bytesize, encoding: Encoding::BINARY)
+        axis_length = horizontal ? width : height
+        radius = weights.length / 2
+        entries = Array.new(axis_length) do |position|
+          weights.each_with_index.map do |weight, index|
+            sample = (position + index - radius).clamp(0, axis_length - 1)
+            [horizontal ? sample * 4 : sample * width * 4, weight]
+          end
+        end
+        height.times do |y|
+          width.times do |x|
+            red = green = blue = alpha = 0.0
+            base = horizontal ? y * width * 4 : x * 4
+            entries[horizontal ? x : y].each do |sample_offset, weight|
+              offset = base + sample_offset
+              sample_alpha = source.getbyte(offset + 3) / 255.0
+              red += source.getbyte(offset) * sample_alpha * weight
+              green += source.getbyte(offset + 1) * sample_alpha * weight
+              blue += source.getbyte(offset + 2) * sample_alpha * weight
+              alpha += source.getbyte(offset + 3) * weight
+            end
+            alpha_byte = alpha.round.clamp(0, 255)
+            if alpha_byte.positive?
+              output << (red * 255 / alpha).round.clamp(0, 255)
+              output << (green * 255 / alpha).round.clamp(0, 255)
+              output << (blue * 255 / alpha).round.clamp(0, 255)
+            else
+              output << "\0\0\0".b
+            end
+            output << alpha_byte
+          end
+        end
+        Tessel::Image.from_rgba(width, height, output, metadata: image.metadata)
+      end
+      private_class_method :convolve_axis
+    end
+  end
+end