ruby_spriter 0.6.5

data/lib/ruby_spriter/metadata_manager.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+module RubySpriter
+  # Manages PNG metadata for spritesheets
+  class MetadataManager
+    METADATA_PREFIX = 'SPRITESHEET'
+
+    # Embed metadata into PNG file
+    # @param input_file [String] Source PNG file
+    # @param output_file [String] Destination PNG file with metadata
+    # @param columns [Integer] Number of columns in grid
+    # @param rows [Integer] Number of rows in grid
+    # @param frames [Integer] Total number of frames
+    # @param debug [Boolean] Enable debug output
+    def self.embed(input_file, output_file, columns:, rows:, frames:, debug: false)
+      Utils::FileHelper.validate_readable!(input_file)
+
+      metadata_str = build_metadata_string(columns, rows, frames)
+      
+      cmd = build_embed_command(input_file, output_file, metadata_str)
+      
+      if debug
+        Utils::OutputFormatter.indent("DEBUG: Metadata command: #{cmd}")
+      end
+
+      stdout, stderr, status = Open3.capture3(cmd)
+
+      unless status.success?
+        raise ProcessingError, "Failed to embed metadata: #{stderr}"
+      end
+
+      Utils::FileHelper.validate_exists!(output_file)
+    end
+
+    # Read metadata from PNG file
+    # @param file [String] PNG file path
+    # @return [Hash, nil] Metadata hash or nil if not found
+    def self.read(file)
+      Utils::FileHelper.validate_readable!(file)
+
+      cmd = build_read_command(file)
+      stdout, stderr, status = Open3.capture3(cmd)
+
+      return nil unless status.success?
+
+      parse_metadata(stdout)
+    end
+
+    # Verify and print metadata from file
+    # @param file [String] PNG file path
+    def self.verify(file)
+      Utils::OutputFormatter.header("Spritesheet Metadata Verification")
+      
+      puts "File: #{file}"
+      puts "Size: #{Utils::FileHelper.format_size(File.size(file))}\n\n"
+
+      metadata = read(file)
+
+      if metadata
+        Utils::OutputFormatter.success("Metadata Found")
+        puts "\n  Grid Layout:"
+        Utils::OutputFormatter.indent("Columns: #{metadata[:columns]}")
+        Utils::OutputFormatter.indent("Rows: #{metadata[:rows]}")
+        Utils::OutputFormatter.indent("Total Frames: #{metadata[:frames]}")
+        Utils::OutputFormatter.indent("Metadata Version: #{metadata[:version]}")
+      else
+        Utils::OutputFormatter.warning("No spritesheet metadata found in this file")
+        puts "\nThis file may not have been created by Ruby Spriter,"
+        puts "or the metadata was stripped during processing."
+      end
+
+      puts "\n" + "=" * 60 + "\n"
+    end
+
+    private_class_method def self.build_metadata_string(columns, rows, frames)
+      "#{METADATA_PREFIX}|columns=#{columns}|rows=#{rows}|frames=#{frames}|version=#{METADATA_VERSION}"
+    end
+
+    private_class_method def self.build_embed_command(input_file, output_file, metadata_str)
+      magick_cmd = Platform.imagemagick_convert_cmd
+      
+      [
+        magick_cmd,
+        Utils::PathHelper.quote_path(input_file),
+        '-set', 'comment', Utils::PathHelper.quote_arg(metadata_str),
+        Utils::PathHelper.quote_path(output_file)
+      ].join(' ')
+    end
+
+    private_class_method def self.build_read_command(file)
+      magick_cmd = Platform.imagemagick_identify_cmd
+      
+      [
+        magick_cmd,
+        '-format', Utils::PathHelper.quote_arg('%c'),
+        Utils::PathHelper.quote_path(file)
+      ].join(' ')
+    end
+
+    private_class_method def self.parse_metadata(output)
+      # Look for SPRITESHEET metadata pattern
+      match = output.match(/#{METADATA_PREFIX}\|columns=(\d+)\|rows=(\d+)\|frames=(\d+)\|version=([\d.]+)/)
+      
+      return nil unless match
+
+      {
+        columns: match[1].to_i,
+        rows: match[2].to_i,
+        frames: match[3].to_i,
+        version: match[4]
+      }
+    end
+  end
+end

data/lib/ruby_spriter/platform.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module RubySpriter
+  # Platform detection and configuration
+  class Platform
+    PLATFORM_TYPE = case RUBY_PLATFORM
+                    when /mingw|mswin|windows/i then :windows
+                    when /linux/i then :linux
+                    when /darwin/i then :macos
+                    else :unknown
+                    end
+
+    # GIMP executable paths by platform
+    GIMP_DEFAULT_PATHS = {
+      windows: 'C:\\Program Files\\GIMP 3\\bin\\gimp-console-3.0.exe',
+      linux: '/usr/bin/gimp',
+      macos: '/Applications/GIMP.app/Contents/MacOS/gimp'
+    }.freeze
+
+    # Alternative GIMP paths to search
+    GIMP_ALTERNATIVE_PATHS = {
+      windows: [
+        'C:\\Program Files\\GIMP 3\\bin\\gimp-console-3.0.exe',
+        'C:\\Program Files (x86)\\GIMP 3\\bin\\gimp-console-3.0.exe',
+        'C:\\Program Files\\GIMP 2\\bin\\gimp-console-2.10.exe',
+        'C:\\Program Files (x86)\\GIMP 2\\bin\\gimp-console-2.10.exe'
+      ].freeze,
+      linux: [
+        '/usr/bin/gimp',
+        '/usr/local/bin/gimp',
+        '/snap/bin/gimp',
+        '/opt/gimp/bin/gimp'
+      ].freeze,
+      macos: [
+        '/Applications/GIMP.app/Contents/MacOS/gimp',
+        '/Applications/GIMP-2.10.app/Contents/MacOS/gimp'
+      ].freeze
+    }.freeze
+
+    class << self
+      # Get the current platform type
+      def current
+        PLATFORM_TYPE
+      end
+
+      # Check if running on Windows
+      def windows?
+        PLATFORM_TYPE == :windows
+      end
+
+      # Check if running on Linux
+      def linux?
+        PLATFORM_TYPE == :linux
+      end
+
+      # Check if running on macOS
+      def macos?
+        PLATFORM_TYPE == :macos
+      end
+
+      # Get default GIMP path for current platform
+      def default_gimp_path
+        GIMP_DEFAULT_PATHS[PLATFORM_TYPE]
+      end
+
+      # Get alternative GIMP paths for current platform
+      def alternative_gimp_paths
+        GIMP_ALTERNATIVE_PATHS[PLATFORM_TYPE] || []
+      end
+
+      # Get ImageMagick convert command name
+      def imagemagick_convert_cmd
+        windows? ? 'magick convert' : 'convert'
+      end
+
+      # Get ImageMagick identify command name
+      def imagemagick_identify_cmd
+        windows? ? 'magick identify' : 'identify'
+      end
+    end
+  end
+end

data/lib/ruby_spriter/processor.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'tmpdir'
+
+module RubySpriter
+  # Main orchestration processor
+  class Processor
+    attr_reader :options, :gimp_path
+
+    def initialize(options = {})
+      @options = default_options.merge(options)
+      @gimp_path = nil
+    end
+
+    # Run the processing workflow
+    def run
+      validate_options!
+      check_dependencies!
+      setup_temp_directory
+
+      result = execute_workflow
+
+      cleanup unless options[:keep_temp]
+
+      result
+    end
+
+    private
+
+    def default_options
+      {
+        video: nil,
+        image: nil,
+        consolidate: nil,
+        verify: nil,
+        output: nil,
+        frame_count: 16,
+        columns: 4,
+        max_width: 320,
+        padding: 0,
+        bg_color: 'black',
+        scale_percent: nil,
+        scale_interpolation: 'nohalo',
+        sharpen: false,
+        sharpen_radius: 2.0,
+        sharpen_gain: 0.5,
+        sharpen_threshold: 0.03,
+        remove_bg: false,
+        bg_threshold: 0.0,
+        grow_selection: 1,
+        fuzzy_select: true,
+        operation_order: :scale_then_remove_bg,
+        validate_columns: true,
+        temp_dir: nil,
+        keep_temp: false,
+        debug: false
+      }
+    end
+
+    def validate_options!
+      input_modes = [options[:video], options[:image], options[:consolidate], options[:verify]].compact
+      
+      if input_modes.empty?
+        raise ValidationError, "Must specify --video, --image, --consolidate, or --verify"
+      end
+
+      if input_modes.length > 1
+        raise ValidationError, "Cannot use multiple input modes together. Choose one."
+      end
+
+      validate_input_files!
+    end
+
+    def validate_input_files!
+      if options[:video]
+        Utils::FileHelper.validate_exists!(options[:video])
+        validate_file_extension!(options[:video], ['.mp4'], '--video')
+      end
+
+      if options[:image]
+        Utils::FileHelper.validate_exists!(options[:image])
+        validate_file_extension!(options[:image], ['.png'], '--image')
+      end
+
+      if options[:consolidate]
+        if options[:consolidate].length < 2
+          raise ValidationError, "--consolidate requires at least 2 files"
+        end
+
+        options[:consolidate].each do |file|
+          Utils::FileHelper.validate_exists!(file)
+          validate_file_extension!(file, ['.png'], '--consolidate')
+        end
+      end
+
+      if options[:verify]
+        Utils::FileHelper.validate_exists!(options[:verify])
+        validate_file_extension!(options[:verify], ['.png'], '--verify')
+      end
+    end
+
+    def validate_file_extension!(file_path, valid_extensions, flag_name)
+      ext = File.extname(file_path).downcase
+      unless valid_extensions.include?(ext)
+        expected = valid_extensions.join(', ')
+        raise ValidationError, "#{flag_name} expects #{expected} file, got: #{ext || '(no extension)'}"
+      end
+    end
+
+    def check_dependencies!
+      checker = DependencyChecker.new(verbose: options[:debug])
+      results = checker.check_all
+
+      # Check required tools
+      missing = []
+      
+      [:ffmpeg, :ffprobe, :imagemagick].each do |tool|
+        missing << tool unless results[tool][:available]
+      end
+
+      # GIMP only needed for image processing
+      if needs_gimp? && !results[:gimp][:available]
+        missing << :gimp
+      end
+
+      if missing.any?
+        checker.print_report
+        raise DependencyError, "Missing required dependencies: #{missing.join(', ')}"
+      end
+
+      @gimp_path = checker.gimp_path if results[:gimp][:available]
+
+      if options[:debug]
+        checker.print_report
+      end
+    end
+
+    def needs_gimp?
+      options[:scale_percent] || options[:remove_bg]
+    end
+
+    def setup_temp_directory
+      @options[:temp_dir] = Dir.mktmpdir('ruby_spriter_')
+      
+      if options[:debug]
+        Utils::OutputFormatter.indent("Temp directory: #{options[:temp_dir]}")
+      end
+    end
+
+    def execute_workflow
+      Utils::OutputFormatter.header("Ruby Spriter v#{VERSION}")
+      puts "Platform: #{Platform.current.to_s.capitalize}"
+      puts "Date: #{VERSION_DATE}\n\n"
+
+      if options[:verify]
+        MetadataManager.verify(options[:verify])
+        return { mode: :verify, file: options[:verify] }
+      end
+
+      if options[:consolidate]
+        return execute_consolidate_workflow
+      elsif options[:image]
+        return execute_image_workflow
+      else
+        return execute_video_workflow
+      end
+    end
+
+    def execute_video_workflow
+      # Step 1: Convert video to spritesheet
+      video_processor = VideoProcessor.new(options)
+      result = video_processor.create_spritesheet(
+        options[:video],
+        options[:output] || Utils::FileHelper.spritesheet_filename(options[:video])
+      )
+
+      working_file = result[:output_file]
+
+      # Step 2: Apply GIMP processing if requested
+      if needs_gimp?
+        working_file = process_with_gimp(working_file)
+      end
+
+      # Step 3: Move to final output location if different
+      if options[:output] && working_file != options[:output]
+        FileUtils.cp(working_file, options[:output])
+        working_file = options[:output]
+      end
+
+      Utils::OutputFormatter.header("SUCCESS!")
+      Utils::OutputFormatter.success("Final output: #{working_file}")
+
+      result.merge(final_output: working_file)
+    end
+
+    def execute_image_workflow
+      working_file = options[:image]
+
+      # Apply GIMP processing if requested
+      if needs_gimp?
+        working_file = process_with_gimp(working_file)
+      end
+
+      # Move to final output location if specified
+      if options[:output] && working_file != options[:output]
+        FileUtils.cp(working_file, options[:output])
+        working_file = options[:output]
+      end
+
+      Utils::OutputFormatter.header("SUCCESS!")
+      Utils::OutputFormatter.success("Final output: #{working_file}")
+
+      {
+        mode: :image,
+        input_file: options[:image],
+        output_file: working_file
+      }
+    end
+
+    def execute_consolidate_workflow
+      consolidator = Consolidator.new(options)
+      
+      output_file = options[:output] || generate_consolidated_filename
+      
+      result = consolidator.consolidate(options[:consolidate], output_file)
+
+      Utils::OutputFormatter.header("SUCCESS!")
+      Utils::OutputFormatter.success("Final output: #{result[:output_file]}")
+
+      result.merge(mode: :consolidate)
+    end
+
+    def process_with_gimp(input_file)
+      gimp_processor = GimpProcessor.new(@gimp_path, options)
+      gimp_processor.process(input_file)
+    end
+
+    def generate_consolidated_filename
+      timestamp = Time.now.strftime('%Y%m%d_%H%M%S')
+      "consolidated_spritesheet_#{timestamp}.png"
+    end
+
+    def cleanup
+      if options[:temp_dir] && Dir.exist?(options[:temp_dir])
+        FileUtils.rm_rf(options[:temp_dir])
+        Utils::OutputFormatter.note("Cleaned up temporary files") if options[:debug]
+      end
+    end
+  end
+end

data/lib/ruby_spriter/utils/file_helper.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module RubySpriter
+  module Utils
+    # File naming and size utilities
+    class FileHelper
+      class << self
+        # Generate spritesheet filename from video file
+        # @param video_file [String] Path to video file
+        # @return [String] Generated spritesheet filename
+        def spritesheet_filename(video_file)
+          dir = File.dirname(video_file)
+          basename = File.basename(video_file, '.*')
+          File.join(dir, "#{basename}_spritesheet.png")
+        end
+
+        # Generate output filename with suffix
+        # @param input_file [String] Original input file
+        # @param suffix [String] Suffix to add to filename
+        # @return [String] Generated output filename
+        def output_filename(input_file, suffix)
+          dir = File.dirname(input_file)
+          basename = File.basename(input_file, '.*')
+          File.join(dir, "#{basename}-#{suffix}.png")
+        end
+
+        # Format file size in human-readable format
+        # @param bytes [Integer] File size in bytes
+        # @return [String] Formatted file size
+        def format_size(bytes)
+          if bytes >= 1024 * 1024
+            "#{(bytes / (1024.0 * 1024.0)).round(2)} MB"
+          elsif bytes >= 1024
+            "#{(bytes / 1024.0).round(2)} KB"
+          else
+            "#{bytes} bytes"
+          end
+        end
+
+        # Validate file exists
+        # @param path [String] File path to validate
+        # @raise [ValidationError] if file doesn't exist
+        def validate_exists!(path)
+          raise ValidationError, "File not found: #{path}" unless File.exist?(path)
+        end
+
+        # Validate file is readable
+        # @param path [String] File path to validate
+        # @raise [ValidationError] if file isn't readable
+        def validate_readable!(path)
+          validate_exists!(path)
+          raise ValidationError, "File not readable: #{path}" unless File.readable?(path)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_spriter/utils/output_formatter.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module RubySpriter
+  module Utils
+    # Console output formatting utilities
+    class OutputFormatter
+      ICONS = {
+        success: '✅',
+        error: '❌',
+        warning: '⚠️',
+        info: 'ℹ️',
+        clean: '🧹',
+        note: '📝'
+      }.freeze
+
+      class << self
+        # Print section header
+        # @param title [String] Section title
+        # @param width [Integer] Header width
+        def header(title, width = 60)
+          puts "\n" + "=" * width
+          puts title
+          puts "=" * width + "\n"
+        end
+
+        # Print success message
+        # @param message [String] Message to print
+        def success(message)
+          puts "#{ICONS[:success]} #{message}"
+        end
+
+        # Print error message
+        # @param message [String] Message to print
+        def error(message)
+          puts "#{ICONS[:error]} #{message}"
+        end
+
+        # Print warning message
+        # @param message [String] Message to print
+        def warning(message)
+          puts "#{ICONS[:warning]} #{message}"
+        end
+
+        # Print info message
+        # @param message [String] Message to print
+        def info(message)
+          puts "#{ICONS[:info]} #{message}"
+        end
+
+        # Print note message
+        # @param message [String] Message to print
+        def note(message)
+          puts "#{ICONS[:note]} #{message}"
+        end
+
+        # Print indented message
+        # @param message [String] Message to print
+        # @param indent [Integer] Number of spaces to indent
+        def indent(message, indent = 6)
+          puts " " * indent + message
+        end
+      end
+    end
+  end
+end

data/lib/ruby_spriter/utils/path_helper.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module RubySpriter
+  module Utils
+    # Cross-platform path handling utilities
+    class PathHelper
+      class << self
+        # Quote a file path for shell execution
+        # @param path [String] The path to quote
+        # @return [String] Properly quoted path
+        def quote_path(path)
+          if Platform.windows?
+            "\"#{path}\""
+          else
+            # Need 4 backslashes because gsub interprets backslashes in replacement string
+            "'#{path.gsub("'", "\\\\'")}'"
+          end
+        end
+
+        # Quote a command argument for shell execution
+        # @param arg [String] The argument to quote
+        # @return [String] Properly quoted argument
+        def quote_arg(arg)
+          if Platform.windows?
+            "\"#{arg}\""
+          else
+            # Need 4 backslashes because gsub interprets backslashes in replacement string
+            "'#{arg.gsub("'", "\\\\'")}'"
+          end
+        end
+
+        # Normalize path for Python scripts (GIMP)
+        # @param path [String] The path to normalize
+        # @return [String] Normalized path with forward slashes
+        def normalize_for_python(path)
+          abs_path = File.absolute_path(path)
+          
+          if Platform.windows?
+            # Use forward slashes for Python raw strings
+            abs_path.gsub('\\', '/')
+          else
+            abs_path
+          end
+        end
+
+        # Convert path to native format
+        # @param path [String] The path to convert
+        # @return [String] Path with platform-appropriate separators
+        def to_native(path)
+          if Platform.windows?
+            path.gsub('/', '\\')
+          else
+            path.gsub('\\', '/')
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_spriter/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RubySpriter
+  VERSION = '0.6.5'
+  VERSION_DATE = '2025-10-23'
+  METADATA_VERSION = '0.6'
+end