ruby_spriter 0.6.5 → 0.6.7

data/lib/ruby_spriter/batch_processor.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module RubySpriter
+  # Processes multiple videos in batch mode
+  class BatchProcessor
+    attr_reader :options
+
+    def initialize(options = {})
+      @options = options
+      validate_directory!
+    end
+
+    # Find all MP4 files in the directory
+    # @return [Array<String>] List of MP4 file paths
+    def find_videos
+      pattern = File.join(options[:dir], '*.mp4')
+      videos = Dir.glob(pattern)
+
+      if videos.empty?
+        raise ValidationError, "No MP4 files found in directory: #{options[:dir]}"
+      end
+
+      if options[:debug]
+        Utils::OutputFormatter.note("Found #{videos.length} video(s) to process")
+        videos.each { |v| Utils::OutputFormatter.indent(File.basename(v)) }
+      end
+
+      videos
+    end
+
+    # Process all videos in the directory
+    # @return [Hash] Processing results with outputs and errors
+    def process
+      videos = find_videos
+      output_dir = determine_output_directory
+      ensure_output_directory_exists(output_dir)
+
+      results = {
+        processed_count: 0,
+        outputs: [],
+        errors: []
+      }
+
+      Utils::OutputFormatter.header("Batch Processing: #{videos.length} video(s)")
+
+      videos.each_with_index do |video, index|
+        begin
+          puts "\nProcessing [#{index + 1}/#{videos.length}]: #{File.basename(video)}"
+
+          output_file = determine_output_file(video, output_dir)
+          output_file = Utils::FileHelper.ensure_unique_output(output_file, overwrite: options[:overwrite])
+
+          # Process video
+          video_result = process_video(video, output_file)
+
+          # Apply max compression if requested
+          if options[:max_compress] && video_result[:output_file]
+            video_result[:output_file] = apply_compression(video_result[:output_file])
+          end
+
+          results[:outputs] << video_result[:output_file]
+          results[:processed_count] += 1
+
+          Utils::OutputFormatter.success("Output: #{File.basename(video_result[:output_file])}")
+        rescue StandardError => e
+          error_msg = "#{File.basename(video)}: #{e.message}"
+          results[:errors] << error_msg
+          Utils::OutputFormatter.error(error_msg)
+        end
+      end
+
+      # Consolidate if requested
+      if options[:batch_consolidate] && results[:outputs].any?
+        consolidated = consolidate_results(results[:outputs])
+        results[:consolidated] = consolidated if consolidated
+      end
+
+      display_summary(results)
+
+      results
+    end
+
+    # Consolidate all resulting spritesheets
+    # @param outputs [Array<String>] List of spritesheet file paths
+    # @return [Hash, nil] Consolidation result or nil if not requested
+    def consolidate_results(outputs)
+      return nil unless options[:batch_consolidate]
+      return nil if outputs.empty?
+
+      Utils::OutputFormatter.header("Consolidating #{outputs.length} spritesheets")
+
+      output_dir = options[:outputdir] || options[:dir]
+      consolidated_file = File.join(output_dir, 'batch_consolidated_spritesheet.png')
+      consolidated_file = Utils::FileHelper.ensure_unique_output(consolidated_file, overwrite: options[:overwrite])
+
+      consolidator = Consolidator.new(options)
+      result = consolidator.consolidate(outputs, consolidated_file)
+
+      Utils::OutputFormatter.success("Consolidated output: #{File.basename(consolidated_file)}")
+
+      result
+    end
+
+    private
+
+    def validate_directory!
+      dir = options[:dir]
+
+      raise ValidationError, "Must specify --dir for batch processing" unless dir
+      raise ValidationError, "Directory not found: #{dir}" unless File.directory?(dir)
+    end
+
+    def determine_output_directory
+      options[:outputdir] || options[:dir]
+    end
+
+    def ensure_output_directory_exists(dir)
+      return if File.directory?(dir)
+
+      if options[:debug]
+        Utils::OutputFormatter.note("Creating output directory: #{dir}")
+      end
+
+      FileUtils.mkdir_p(dir)
+    end
+
+    def determine_output_file(video_file, output_dir)
+      basename = File.basename(video_file, '.*')
+      File.join(output_dir, "#{basename}_spritesheet.png")
+    end
+
+    def process_video(video_file, output_file)
+      video_processor = VideoProcessor.new(options)
+      result = video_processor.create_spritesheet(video_file, output_file)
+
+      working_file = result[:output_file]
+
+      # Apply GIMP processing if requested
+      if needs_gimp_processing?
+        working_file = process_with_gimp(working_file, result)
+      end
+
+      # Update result with final file
+      result[:output_file] = working_file
+      result
+    end
+
+    def needs_gimp_processing?
+      options[:scale_percent] || options[:remove_bg] || options[:sharpen]
+    end
+
+    def process_with_gimp(input_file, video_result)
+      # Get GIMP path from dependency checker
+      checker = DependencyChecker.new(verbose: false)
+      results = checker.check_all
+      gimp_path = checker.gimp_path
+
+      unless gimp_path
+        raise DependencyError, "GIMP not found but required for processing"
+      end
+
+      gimp_processor = GimpProcessor.new(gimp_path, options)
+      output_file = gimp_processor.process(input_file)
+
+      # Clean up intermediate file if different
+      if output_file != input_file && File.exist?(input_file)
+        File.delete(input_file) unless options[:keep_temp]
+      end
+
+      output_file
+    end
+
+    def apply_compression(file)
+      Utils::OutputFormatter.indent("Applying maximum compression...")
+
+      temp_file = file.gsub('.png', '_temp.png')
+      CompressionManager.compress_with_metadata(file, temp_file)
+
+      # Show compression stats
+      if options[:debug]
+        stats = CompressionManager.compression_stats(file, temp_file)
+        Utils::OutputFormatter.indent("Saved #{Utils::FileHelper.format_size(stats[:saved_bytes])} (#{stats[:reduction_percent].round(1)}% reduction)")
+      end
+
+      # Replace original with compressed
+      FileUtils.mv(temp_file, file)
+
+      file
+    end
+
+    def display_summary(results)
+      Utils::OutputFormatter.header("Batch Processing Summary")
+
+      puts "Total videos: #{results[:processed_count] + results[:errors].length}"
+      Utils::OutputFormatter.success("Successfully processed: #{results[:processed_count]}")
+
+      if results[:errors].any?
+        Utils::OutputFormatter.error("Failed: #{results[:errors].length}")
+        results[:errors].each do |error|
+          Utils::OutputFormatter.indent("- #{error}")
+        end
+      end
+
+      if results[:consolidated]
+        puts "\nConsolidated spritesheet:"
+        Utils::OutputFormatter.indent(results[:consolidated][:output_file])
+      end
+    end
+  end
+end

data/lib/ruby_spriter/cli.rb

@@ -18,6 +18,12 @@ module RubySpriter
 
     def parse_and_run(args)
       options = {}
+
+      # Handle context-sensitive help before validation
+      if args.include?('--help') || args.include?('-h')
+        handle_context_sensitive_help(args)
+      end
+
       parser = build_option_parser(options)
 
       parser.parse!(args)
@@ -29,6 +35,16 @@ module RubySpriter
         exit(checker.all_satisfied? ? 0 : 1)
       end
 
+      # Validate mutually exclusive options
+      if options[:extract] && options[:split]
+        raise ValidationError, "--extract and --split are mutually exclusive"
+      end
+
+      # Validate --add-meta cannot be combined with processing options
+      if options[:add_meta] && (options[:scale_percent] || options[:remove_bg] || options[:sharpen])
+        raise ValidationError, "--add-meta cannot be combined with processing options (--scale, --remove-bg, --sharpen)"
+      end
+
       # Run processor
       processor = Processor.new(options)
       processor.run
@@ -57,14 +73,21 @@ module RubySpriter
 
     def add_header(opts)
       opts.separator ""
-      opts.separator "Ruby Spriter v#{VERSION} - MP4 to Spritesheet + GIMP Processing"
+      opts.separator "Ruby Spriter v#{VERSION} - Professional MP4 to Spritesheet Converter with Advanced Image Processing"
       opts.separator "Platform: #{Platform.current.to_s.capitalize}"
       opts.separator ""
+      opts.separator "Get mode-specific help:"
+      opts.separator "  ruby_spriter --video --help"
+      opts.separator "  ruby_spriter --image --help"
+      opts.separator "  ruby_spriter --consolidate --help"
+      opts.separator "  ruby_spriter --batch --help"
+      opts.separator "  ruby_spriter --split --help"
+      opts.separator ""
     end
 
     def add_input_options(opts, options)
       opts.separator "Input Options:"
-      
+
       opts.on("-v", "--video FILE", "Input video file (MP4)") do |v|
         options[:video] = v
       end
@@ -73,14 +96,55 @@ module RubySpriter
         options[:image] = i
       end
 
-      opts.on("--consolidate FILES", Array, "Consolidate multiple spritesheets (comma-separated)") do |c|
-        options[:consolidate] = c
+      opts.on("--batch", "Batch process all MP4 files in directory") do
+        options[:batch] = true
+      end
+
+      opts.on("--dir DIRECTORY", "Directory for batch processing") do |d|
+        options[:dir] = d
+      end
+
+      opts.on("--outputdir DIRECTORY", "Output directory for batch processing") do |d|
+        options[:outputdir] = d
+      end
+
+      opts.on("--batch-consolidate", "Consolidate all spritesheets after batch processing") do
+        options[:batch_consolidate] = true
+      end
+
+      opts.on("--consolidate [FILES]", Array, "Consolidate spritesheets (comma-separated files or use with --dir)") do |c|
+        options[:consolidate_mode] = true
+        options[:consolidate] = c if c && !c.empty?
       end
 
       opts.on("--verify FILE", "Verify spritesheet metadata") do |v|
         options[:verify] = v
       end
 
+      opts.on("--split R:C", "Split image into frames (rows:columns, e.g., 4:4)") do |s|
+        options[:split] = s
+      end
+
+      opts.on("--override-md", "Override embedded metadata when using --split") do
+        options[:override_md] = true
+      end
+
+      opts.on("--extract FRAMES", "Extract specific frames by number (comma-separated, e.g., 1,2,4,5,8)") do |e|
+        options[:extract] = e
+      end
+
+      opts.on("--columns NUM", Integer, "Number of columns for extracted spritesheet (default: 4)") do |c|
+        options[:columns] = c
+      end
+
+      opts.on("--add-meta R:C", "Add spritesheet metadata to image (rows:columns, e.g., 4:4)") do |m|
+        options[:add_meta] = m
+      end
+
+      opts.on("--overwrite-meta", "Overwrite existing metadata when using --add-meta") do
+        options[:overwrite_meta] = true
+      end
+
       opts.separator ""
     end
 
@@ -107,11 +171,15 @@ module RubySpriter
         options[:bg_color] = b
       end
 
+      opts.on("--save-frames", "Save individual frames to disk (for --video or --extract)") do
+        options[:save_frames] = true
+      end
+
       opts.separator ""
     end
 
     def add_gimp_options(opts, options)
-      opts.separator "GIMP Processing Options:"
+      opts.separator "Processing Options:"
 
       opts.on("-s", "--scale PERCENT", Integer, "Scale image by percentage") do |s|
         options[:scale_percent] = s
@@ -138,7 +206,7 @@ module RubySpriter
         options[:sharpen_threshold] = t
       end
 
-      opts.on("-r", "--remove-bg", "Remove background from spritesheet using GIMP") do
+      opts.on("-r", "--remove-bg", "Remove background from spritesheet") do
         options[:remove_bg] = true
       end
 
@@ -208,6 +276,14 @@ module RubySpriter
     def add_other_options(opts, options)
       opts.separator "Other Options:"
 
+      opts.on("--max-compress", "Apply maximum PNG compression to output") do
+        options[:max_compress] = true
+      end
+
+      opts.on("--overwrite", "Overwrite existing output files (default: create unique filenames)") do
+        options[:overwrite] = true
+      end
+
       opts.on("--keep-temp", "Keep temporary files for debugging") do
         options[:keep_temp] = true
       end
@@ -239,11 +315,298 @@ module RubySpriter
       opts.separator "  ruby_spriter --video input.mp4"
       opts.separator "  ruby_spriter --video input.mp4 --remove-bg --scale 50"
       opts.separator "  ruby_spriter --video input.mp4 --scale 50 --interpolation nohalo --sharpen"
+      opts.separator "  ruby_spriter --video input.mp4 --max-compress"
       opts.separator "  ruby_spriter --image sprite.png --scale 50 --sharpen --sharpen-gain 1.5"
       opts.separator "  ruby_spriter --image sprite.png --remove-bg --fuzzy"
+      opts.separator "  ruby_spriter --batch --dir videos/"
+      opts.separator "  ruby_spriter --batch --dir videos/ --outputdir output/"
+      opts.separator "  ruby_spriter --batch --dir videos/ --batch-consolidate --max-compress"
       opts.separator "  ruby_spriter --consolidate file1.png,file2.png,file3.png"
+      opts.separator "  ruby_spriter --consolidate --dir spritesheets/"
+      opts.separator "  ruby_spriter --consolidate --dir spritesheets/ --outputdir output/ --max-compress"
       opts.separator "  ruby_spriter --verify spritesheet.png"
       opts.separator ""
     end
+
+    def handle_context_sensitive_help(args)
+      if args.include?('--video') || args.include?('-v')
+        show_video_mode_help
+      elsif args.include?('--image') || args.include?('-i')
+        show_image_mode_help
+      elsif args.include?('--consolidate')
+        show_consolidate_mode_help
+      elsif args.include?('--batch')
+        show_batch_mode_help
+      elsif args.include?('--split')
+        show_split_mode_help
+      else
+        # Default help - let OptionParser handle it
+        return
+      end
+    end
+
+    def show_video_mode_help
+      puts ""
+      puts "Video Mode"
+      puts "=" * 60
+      puts ""
+      puts "Convert MP4 videos to spritesheets with advanced image processing."
+      puts ""
+      puts "Basic Usage:"
+      puts "  ruby_spriter --video FILE [options]"
+      puts ""
+      puts "Required:"
+      puts "  -v, --video FILE                 Input video file (MP4)"
+      puts ""
+      puts "Spritesheet Options:"
+      puts "  -o, --output FILE                Output file path"
+      puts "  -f, --frames COUNT               Number of frames to extract (default: 16)"
+      puts "  -c, --columns COUNT              Grid columns (default: 4)"
+      puts "  -w, --width PIXELS               Max frame width (default: 320)"
+      puts "  -b, --background COLOR           Tile background: black, white (default: black)"
+      puts "  --save-frames                    Save individual frames to disk"
+      puts ""
+      puts "Image Processing:"
+      puts "  -s, --scale PERCENT              Scale image by percentage"
+      puts "    --interpolation METHOD         └─ Interpolation: none, linear, cubic, nohalo, lohalo (default: nohalo)"
+      puts ""
+      puts "  --sharpen                        Apply unsharp mask for edge enhancement"
+      puts "    --sharpen-radius VALUE         └─ Sharpen radius in pixels (default: 2.0)"
+      puts "    --sharpen-gain VALUE           └─ Sharpen gain/strength (default: 0.5)"
+      puts "    --sharpen-threshold VALUE      └─ Sharpen threshold (default: 0.03)"
+      puts ""
+      puts "  -r, --remove-bg                  Remove background"
+      puts "    --fuzzy                        └─ Use fuzzy select (contiguous regions) - DEFAULT"
+      puts "    --no-fuzzy                     └─ Use global color select (all matching pixels)"
+      puts "    -t, --threshold VALUE          └─ Feather radius (default: 0.0)"
+      puts "    -g, --grow PIXELS              └─ Grow selection pixels (default: 1)"
+      puts ""
+      puts "  --order ORDER                    Operation order when using BOTH --scale AND --remove-bg:"
+      puts "                                   scale_first or bg_first (default: scale_first)"
+      puts ""
+      puts "Output Options:"
+      puts "  --max-compress                   Apply maximum PNG compression"
+      puts "  --overwrite                      Overwrite existing files"
+      puts "  --keep-temp                      Keep temporary files"
+      puts "  --debug                          Enable debug mode"
+      puts ""
+      puts "Examples:"
+      puts "  ruby_spriter --video input.mp4"
+      puts "  ruby_spriter --video input.mp4 --scale 50 --interpolation nohalo"
+      puts "  ruby_spriter --video input.mp4 --remove-bg --fuzzy --threshold 0.5"
+      puts "  ruby_spriter --video input.mp4 --scale 50 --sharpen --max-compress"
+      puts ""
+      exit
+    end
+
+    def show_image_mode_help
+      puts ""
+      puts "Image Mode"
+      puts "=" * 60
+      puts ""
+      puts "Process PNG spritesheets with advanced image operations."
+      puts ""
+      puts "Basic Usage:"
+      puts "  ruby_spriter --image FILE [options]"
+      puts ""
+      puts "Required:"
+      puts "  -i, --image FILE                 Input image file (PNG)"
+      puts ""
+      puts "Image Processing:"
+      puts "  -s, --scale PERCENT              Scale image by percentage"
+      puts "    --interpolation METHOD         └─ Interpolation: none, linear, cubic, nohalo, lohalo (default: nohalo)"
+      puts ""
+      puts "  --sharpen                        Apply unsharp mask for edge enhancement"
+      puts "    --sharpen-radius VALUE         └─ Sharpen radius in pixels (default: 2.0)"
+      puts "    --sharpen-gain VALUE           └─ Sharpen gain/strength (default: 0.5)"
+      puts "    --sharpen-threshold VALUE      └─ Sharpen threshold (default: 0.03)"
+      puts ""
+      puts "  -r, --remove-bg                  Remove background"
+      puts "    --fuzzy                        └─ Use fuzzy select (contiguous regions) - DEFAULT"
+      puts "    --no-fuzzy                     └─ Use global color select (all matching pixels)"
+      puts "    -t, --threshold VALUE          └─ Feather radius (default: 0.0)"
+      puts "    -g, --grow PIXELS              └─ Grow selection pixels (default: 1)"
+      puts ""
+      puts "  --order ORDER                    Operation order when using BOTH --scale AND --remove-bg:"
+      puts "                                   scale_first or bg_first (default: scale_first)"
+      puts ""
+      puts "Frame Extraction & Reassembly:"
+      puts "  --split R:C                      Split spritesheet into all individual frames (rows:columns)"
+      puts "    --override-md                  └─ Override embedded metadata"
+      puts ""
+      puts "  --extract FRAMES                 Extract specific frames and create new spritesheet (e.g., 1,2,4,5,8)"
+      puts "    --columns NUM                  └─ Output grid columns (default: 4)"
+      puts "    --save-frames                  └─ Keep individual extracted frames on disk"
+      puts ""
+      puts "Metadata Management:"
+      puts "  --add-meta R:C                   Add spritesheet metadata (rows:columns, e.g., 4:4)"
+      puts "    --overwrite-meta               └─ Replace existing metadata"
+      puts "    -f, --frames COUNT             └─ Custom frame count for partial grids"
+      puts ""
+      puts "Output Options:"
+      puts "  -o, --output FILE                Output file path"
+      puts "  --max-compress                   Apply maximum PNG compression"
+      puts "  --overwrite                      Overwrite existing files"
+      puts "  --keep-temp                      Keep temporary files"
+      puts "  --debug                          Enable debug mode"
+      puts ""
+      puts "Examples:"
+      puts "  ruby_spriter --image sprite.png --scale 50 --interpolation nohalo"
+      puts "  ruby_spriter --image sprite.png --remove-bg --fuzzy --threshold 1.0"
+      puts "  ruby_spriter --image sprite.png --scale 50 --sharpen --sharpen-gain 1.5"
+      puts "  ruby_spriter --image sprite.png --split 4:4 --override-md"
+      puts "  ruby_spriter --image sprite.png --extract 1,2,4,5,8 --columns 3"
+      puts "  ruby_spriter --image sprite.png --extract 1,1,2,2,3,3 --save-frames"
+      puts "  ruby_spriter --image sprite.png --add-meta 4:4"
+      puts "  ruby_spriter --image sprite.png --add-meta 4:4 --frames 14 --output sprite_meta.png"
+      puts ""
+      exit
+    end
+
+    def show_consolidate_mode_help
+      puts ""
+      puts "Consolidate Mode"
+      puts "=" * 60
+      puts ""
+      puts "Combine multiple spritesheets into a single consolidated spritesheet."
+      puts ""
+      puts "Basic Usage:"
+      puts "  ruby_spriter --consolidate FILE1,FILE2,FILE3 [options]"
+      puts "  ruby_spriter --consolidate --dir DIRECTORY [options]"
+      puts ""
+      puts "Input Methods:"
+      puts "  --consolidate [FILES]            Comma-separated list of PNG files"
+      puts "  --consolidate --dir DIRECTORY    Process all spritesheets in directory"
+      puts "    --[no-]validate-columns        └─ Abort if column counts don't match (default: true)"
+      puts ""
+      puts "Output Options:"
+      puts "  -o, --output FILE                Output file path"
+      puts "  --outputdir DIRECTORY            Output directory (when using --dir)"
+      puts "  --max-compress                   Apply maximum PNG compression"
+      puts "  --overwrite                      Overwrite existing files"
+      puts "  --keep-temp                      Keep temporary files"
+      puts "  --debug                          Enable debug mode"
+      puts ""
+      puts "Requirements:"
+      puts "  - All input files must be PNG spritesheets with embedded metadata"
+      puts "  - Column counts must match across all spritesheets (unless --no-validate-columns)"
+      puts "  - Minimum 2 spritesheets required"
+      puts ""
+      puts "Examples:"
+      puts "  ruby_spriter --consolidate file1.png,file2.png,file3.png"
+      puts "  ruby_spriter --consolidate --dir spritesheets/"
+      puts "  ruby_spriter --consolidate --dir spritesheets/ --outputdir output/"
+      puts "  ruby_spriter --consolidate --dir spritesheets/ --no-validate-columns"
+      puts ""
+      exit
+    end
+
+    def show_batch_mode_help
+      puts ""
+      puts "Batch Mode"
+      puts "=" * 60
+      puts ""
+      puts "Process multiple MP4 videos in a directory with consistent options."
+      puts ""
+      puts "Basic Usage:"
+      puts "  ruby_spriter --batch --dir DIRECTORY [options]"
+      puts ""
+      puts "Required:"
+      puts "  --batch                          Enable batch processing mode"
+      puts "  --dir DIRECTORY                  Directory containing MP4 files"
+      puts ""
+      puts "Batch Options:"
+      puts "  --outputdir DIRECTORY            Output directory (default: same as input dir)"
+      puts "  --batch-consolidate              Consolidate all results into single spritesheet"
+      puts ""
+      puts "Spritesheet Options (applied to all videos):"
+      puts "  -f, --frames COUNT               Number of frames to extract (default: 16)"
+      puts "  -c, --columns COUNT              Grid columns (default: 4)"
+      puts "  -w, --width PIXELS               Max frame width (default: 320)"
+      puts "  -b, --background COLOR           Tile background: black, white (default: black)"
+      puts "  --save-frames                    Save individual frames to disk"
+      puts ""
+      puts "Image Processing (applied to all videos):"
+      puts "  -s, --scale PERCENT              Scale images by percentage"
+      puts "    --interpolation METHOD         └─ Interpolation: none, linear, cubic, nohalo, lohalo (default: nohalo)"
+      puts ""
+      puts "  --sharpen                        Apply unsharp mask for edge enhancement"
+      puts "    --sharpen-radius VALUE         └─ Sharpen radius (default: 2.0)"
+      puts "    --sharpen-gain VALUE           └─ Sharpen gain (default: 0.5)"
+      puts "    --sharpen-threshold VALUE      └─ Sharpen threshold (default: 0.03)"
+      puts ""
+      puts "  -r, --remove-bg                  Remove background"
+      puts "    --fuzzy                        └─ Use fuzzy select (DEFAULT)"
+      puts "    --no-fuzzy                     └─ Use global color select"
+      puts "    -t, --threshold VALUE          └─ Feather radius (default: 0.0)"
+      puts "    -g, --grow PIXELS              └─ Grow selection (default: 1)"
+      puts ""
+      puts "  --order ORDER                    Operation order when using BOTH --scale AND --remove-bg:"
+      puts "                                   scale_first or bg_first (default: scale_first)"
+      puts ""
+      puts "Output Options:"
+      puts "  --max-compress                   Apply maximum PNG compression"
+      puts "  --overwrite                      Overwrite existing files"
+      puts "  --keep-temp                      Keep temporary files"
+      puts "  --debug                          Enable debug mode"
+      puts ""
+      puts "Behavior:"
+      puts "  - Processes all MP4 files in the specified directory"
+      puts "  - Enforces unique filenames unless --overwrite is specified"
+      puts "  - Continues processing remaining videos if one fails"
+      puts "  - Provides summary of successes and failures"
+      puts ""
+      puts "Examples:"
+      puts "  ruby_spriter --batch --dir videos/"
+      puts "  ruby_spriter --batch --dir videos/ --outputdir output/"
+      puts "  ruby_spriter --batch --dir videos/ --scale 50 --sharpen"
+      puts "  ruby_spriter --batch --dir videos/ --batch-consolidate --max-compress"
+      puts ""
+      exit
+    end
+
+    def show_split_mode_help
+      puts ""
+      puts "Split Mode"
+      puts "=" * 60
+      puts ""
+      puts "Extract individual frames from a spritesheet (requires --image)."
+      puts ""
+      puts "Basic Usage:"
+      puts "  ruby_spriter --image FILE --split R:C [options]"
+      puts ""
+      puts "Required:"
+      puts "  -i, --image FILE                 Input spritesheet file (PNG)"
+      puts "  --split R:C                      Split format: rows:columns (e.g., 4:4)"
+      puts "    --override-md                  └─ Override embedded metadata"
+      puts ""
+      puts "Format Requirements:"
+      puts "  - Rows and columns must be 1-99"
+      puts "  - Total frames (R × C) must be < 1000"
+      puts "  - Image dimensions must divide evenly by rows and columns"
+      puts ""
+      puts "Metadata Behavior:"
+      puts "  - If spritesheet has embedded metadata, it will be used automatically"
+      puts "  - Use --override-md to ignore embedded metadata and use --split value"
+      puts "  - If no metadata exists, --split value is required"
+      puts ""
+      puts "Output Options:"
+      puts "  -o, --output FILE                Output directory (default: filename_frames/)"
+      puts "  --overwrite                      Overwrite existing files"
+      puts "  --keep-temp                      Keep temporary files"
+      puts "  --debug                          Enable debug mode"
+      puts ""
+      puts "Output:"
+      puts "  - Frames are saved as: FR001_filename.png, FR002_filename.png, etc."
+      puts "  - Frame naming uses 3-digit zero-padded format (FR001-FR999)"
+      puts "  - Output directory: filename_frames/ (unless --output specified)"
+      puts ""
+      puts "Examples:"
+      puts "  ruby_spriter --image sprite.png --split 4:4"
+      puts "  ruby_spriter --image sprite.png --split 8:8 --override-md"
+      puts "  ruby_spriter --image sprite.png --split 2:5 --output frames/"
+      puts ""
+      exit
+    end
   end
 end