ruby_spriter 0.6.5 → 0.6.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f794b569ca3be84a3e33923a645ee3f98a8771d12d1e9befc5bc9f63241d079d
-  data.tar.gz: b8e2078fa01d7095ec071c83e6d0e17683f86b2653a8f610b50925084e9d4984
+  metadata.gz: b6e4b3befadf222f9fe4a13b50eb16a5a39124c45f5dad2769f7c4f9153aae4f
+  data.tar.gz: 9f13e8d5da4c706a3d834f5a8d125ee46a1d7f04e5a643c90bda451bdb7f6e9c
 SHA512:
-  metadata.gz: 7fea2f1769c71ae55b040b41c6f1dd29f8d1c384eda0606464fee0c26892d48463586f541a484395c3368170484028488bc3bc6b7f1820f20132ec004fc5ae81
-  data.tar.gz: a751cdce97247fc81627bb3a0d4628c5c560885ce4df8eed744c9923bdd8cb86842c07363e02cc66ff94f2792ff8a50504b980ba7035e559014e1bc24f692985
+  metadata.gz: 8b05aec242fb65fb3f8745e276f7ec35ce2d05884f62e9b5af8fcef896a8f66ba2050c48d9c6e6c7400ad4ba93215225e5624c04bba25417e32dfff2e255b345
+  data.tar.gz: 97631e37ef5cbe5bb544526d1e696a870dc9cb26759d2838b1af4f77d81e03696f717225f3858ac55bd2a2ecdd3e86dbe6a4e8c91dc4ac8c75f52f7ff1df68e3

data/CHANGELOG.md

@@ -12,6 +12,56 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.6.6] - 2025-10-23
+
+### 🔒 File Protection & Frame Extraction Release
+
+#### Added
+- **Automatic Unique Filenames**: By default, generates timestamped filenames to prevent accidental overwrites
+  - Format: `filename_YYYYMMDD_HHMMSS_mmm.ext` (includes milliseconds)
+  - Applies to all output modes: `--video`, `--image`, `--consolidate`
+  - Works with both auto-generated and `--output` specified filenames
+- **`--overwrite` Flag**: Optional flag to explicitly allow overwriting existing files
+- **`--split R:C` Option**: Split spritesheets into individual frames for `--image` workflow
+  - Format: `--split 4:4` (rows:columns, e.g., 4 rows × 4 columns)
+  - Validation: Rows and columns must be 1-99, total frames < 1000
+  - Frame naming: `FRddd_filename.png` (3-digit zero-padded format: FR001, FR002, ..., FR999)
+  - Output directory: `filename_frames/`
+  - Metadata priority: Uses embedded metadata if available, unless `--override-md` flag is provided
+  - Dimension validation: Image dimensions must divide evenly by specified rows and columns
+- **`--override-md` Flag**: Override embedded metadata when using `--split` with images that have metadata
+- **Intermediate File Cleanup**: Fixed cleanup of intermediate files from GIMP processing
+  - Now correctly removes files with dash separator (e.g., `file-nobg-fuzzy.png`, `file-scaled-40pct.png`)
+  - Added Windows-compatible path normalization for file comparison
+- **Frame Extraction Tests**: 17 new comprehensive tests for split functionality
+  - CLI option tests for `--split` and `--override-md`
+  - Format and range validation tests (10 tests)
+  - Metadata priority logic tests (5 tests)
+  - Updated SpritesheetSplitter tests for FR%03d format
+
+#### Changed
+- **Default Behavior**: Changed from overwriting to creating unique files (breaking change, but safer)
+- **GimpProcessor**: Now respects `--overwrite` flag for scaled and background-removed images
+- **Consolidate Workflow**: Default filename changed from `consolidated_spritesheet_TIMESTAMP.png` to `consolidated_spritesheet.png` (uniqueness handled by flag)
+- **Frame Naming Format**: Changed from FR%02d (2 digits) to FR%03d (3 digits) to support up to 999 frames
+- **Intermediate File Pattern**: Fixed glob pattern from underscore to dash separator for GIMP output files
+
+#### Technical Details
+- New utility methods in `Utils::FileHelper`:
+  - `unique_filename(path)` - Generates timestamped filename if file exists
+  - `ensure_unique_output(path, overwrite:)` - Applies overwrite logic
+- New methods in `Processor`:
+  - `validate_split_option!` - Validates split format and ranges during initialization
+  - `determine_split_parameters(image_file)` - Implements metadata priority logic
+  - `validate_image_dimensions(image_file, rows, columns)` - Validates even division
+- Processor workflows updated to use `ensure_unique_output` for all output paths
+- `SpritesheetSplitter` updated to use 3-digit frame format (FR%03d)
+- Test coverage increased to 72.27% (688/952 lines)
+
+Closes #17, #19, #30
+
+---
+
 ## [0.6.5] - 2025-10-23
 
 ### 📦 Distribution & Packaging Release

data/README.md

@@ -1,4 +1,4 @@
-# Ruby Spriter v0.6.5
+# Ruby Spriter v0.6.6
 
 [![Ruby](https://img.shields.io/badge/Ruby-2.7+-red.svg)](https://www.ruby-lang.org/)
 [![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
@@ -18,6 +18,7 @@ A powerful cross-platform Ruby tool for creating high-quality spritesheets from
 - 🎨 **Quality Enhancement** - 5 interpolation methods and configurable unsharp masking
 - 📐 **Spritesheet Consolidation** - Merge multiple spritesheets vertically
 - 📊 **Metadata Management** - Embed and verify grid information in PNG files
+- 🔒 **Automatic File Protection** - Unique timestamped filenames prevent accidental overwrites (v0.6.6+)
 - 🌍 **Cross-Platform** - Works seamlessly on Windows, Linux, and macOS
 - 🧪 **Production Ready** - Comprehensive RSpec test coverage
 
@@ -134,7 +135,7 @@ bundle install
 
 # Build and install gem locally
 gem build ruby_spriter.gemspec
-gem install ruby_spriter-0.6.5.gem
+gem install ruby_spriter-0.6.6.gem
 ```
 
 **Best for**: Contributors, developers wanting latest code
@@ -286,6 +287,7 @@ ruby_spriter --consolidate file1.png,file2.png,file3.png \
 
 #### **Other Options**
 ```bash
+    --overwrite               Overwrite existing output files (default: create unique filenames)
     --keep-temp               Keep temporary files for debugging
     --debug                   Enable verbose output + keep temp files
     --check-dependencies      Check if all required external tools are installed
@@ -340,6 +342,42 @@ ruby_spriter --image 4k_sprite.png \
 
 ## 🔧 Advanced Features
 
+### File Protection with Unique Filenames (v0.6.6+)
+
+By default, Ruby Spriter protects your existing files by generating unique timestamped filenames when output files already exist:
+
+```bash
+# First run - creates new file
+ruby_spriter --image sprite.png --remove-bg
+# Output: sprite-nobg-fuzzy.png
+
+# Second run - creates unique file instead of overwriting
+ruby_spriter --image sprite.png --remove-bg
+# Output: sprite-nobg-fuzzy_20251023_170542_123.png
+
+# Third run - another unique file
+ruby_spriter --image sprite.png --remove-bg
+# Output: sprite-nobg-fuzzy_20251023_170545_456.png
+```
+
+#### Overwrite Mode
+
+Use `--overwrite` to replace existing files instead:
+
+```bash
+# Always overwrites sprite-nobg-fuzzy.png
+ruby_spriter --image sprite.png --remove-bg --overwrite
+```
+
+#### Behavior by Mode
+
+| Mode | Default Filename | Unique on Collision |
+|------|------------------|---------------------|
+| `--video` | `input_spritesheet.png` | ✅ Yes |
+| `--image` (with processing) | `input-scaled-50pct.png` | ✅ Yes |
+| `--consolidate` | `consolidated_spritesheet.png` | ✅ Yes |
+| Any with `--output` | Your specified name | ✅ Yes (unless `--overwrite`) |
+
 ### Metadata Management
 
 Ruby Spriter embeds grid information directly into PNG files:

data/lib/ruby_spriter/cli.rb

@@ -81,6 +81,14 @@ module RubySpriter
         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.separator ""
     end
 
@@ -107,6 +115,10 @@ module RubySpriter
         options[:bg_color] = b
       end
 
+      opts.on("--save-frames", "Save individual frames to disk (video only)") do
+        options[:save_frames] = true
+      end
+
       opts.separator ""
     end
 
@@ -208,6 +220,10 @@ module RubySpriter
     def add_other_options(opts, options)
       opts.separator "Other Options:"
 
+      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

data/lib/ruby_spriter/gimp_processor.rb

@@ -68,7 +68,8 @@ module RubySpriter
 
     def scale_image(input_file)
       percent = options[:scale_percent]
-      output_file = Utils::FileHelper.output_filename(input_file, "scaled-#{percent}pct")
+      desired_output = Utils::FileHelper.output_filename(input_file, "scaled-#{percent}pct")
+      output_file = Utils::FileHelper.ensure_unique_output(desired_output, overwrite: options[:overwrite])
 
       Utils::OutputFormatter.indent("Scaling to #{percent}%...")
 
@@ -85,7 +86,8 @@ module RubySpriter
 
     def remove_background(input_file)
       method = options[:fuzzy_select] ? 'fuzzy' : 'global'
-      output_file = Utils::FileHelper.output_filename(input_file, "nobg-#{method}")
+      desired_output = Utils::FileHelper.output_filename(input_file, "nobg-#{method}")
+      output_file = Utils::FileHelper.ensure_unique_output(desired_output, overwrite: options[:overwrite])
 
       Utils::OutputFormatter.indent("Removing background (#{method} select)...")
 
@@ -621,7 +623,8 @@ module RubySpriter
       gain = options[:sharpen_gain] || 0.5
       threshold = options[:sharpen_threshold] || 0.03
 
-      output_file = Utils::FileHelper.output_filename(input_file, "sharpened")
+      desired_output = Utils::FileHelper.output_filename(input_file, "sharpened")
+      output_file = Utils::FileHelper.ensure_unique_output(desired_output, overwrite: options[:overwrite])
 
       Utils::OutputFormatter.indent("Applying unsharp mask (ImageMagick)...")
       Utils::OutputFormatter.indent("  radius=#{radius}, gain=#{gain}, threshold=#{threshold}")

data/lib/ruby_spriter/processor.rb

@@ -2,15 +2,31 @@
 
 require 'fileutils'
 require 'tmpdir'
+require 'open3'
 
 module RubySpriter
   # Main orchestration processor
   class Processor
-    attr_reader :options, :gimp_path
+    attr_reader :options, :gimp_path, :split_rows, :split_columns
+
+    # Valid ranges for numeric options
+    VALID_RANGES = {
+      frame_count: { min: 1, max: 10000, type: Integer },
+      columns: { min: 1, max: 100, type: Integer },
+      max_width: { min: 1, max: 1920, type: Integer },
+      scale_percent: { min: 1, max: 500, type: Integer },
+      grow_selection: { min: 0, max: 100, type: Integer },
+      sharpen_radius: { min: 0.1, max: 100.0, type: Float },
+      sharpen_gain: { min: 0.0, max: 10.0, type: Float },
+      sharpen_threshold: { min: 0.0, max: 1.0, type: Float },
+      bg_threshold: { min: 0.0, max: 100.0, type: Float }
+    }.freeze
 
     def initialize(options = {})
       @options = default_options.merge(options)
       @gimp_path = nil
+      validate_numeric_options!
+      validate_split_option!
     end
 
     # Run the processing workflow
@@ -54,13 +70,17 @@ module RubySpriter
         validate_columns: true,
         temp_dir: nil,
         keep_temp: false,
-        debug: false
+        debug: false,
+        overwrite: false,
+        save_frames: false,
+        split: nil,
+        override_md: 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
@@ -70,6 +90,8 @@ module RubySpriter
       end
 
       validate_input_files!
+      validate_numeric_options!
+      validate_split_option!
     end
 
     def validate_input_files!
@@ -108,6 +130,53 @@ module RubySpriter
       end
     end
 
+    def validate_numeric_options!
+      VALID_RANGES.each do |option_name, range_config|
+        value = options[option_name]
+
+        # Skip validation if option is not set (nil)
+        next if value.nil?
+
+        min = range_config[:min]
+        max = range_config[:max]
+
+        # Validate that value is within range
+        if value < min || value > max
+          raise ValidationError, "#{option_name} must be between #{min} and #{max}, got: #{value}"
+        end
+      end
+    end
+
+    def validate_split_option!
+      return unless options[:split]
+
+      # Parse split format: R:C
+      unless options[:split] =~ /^\d+:\d+$/
+        raise ValidationError, "Invalid --split format. Use R:C (e.g., 4:4)"
+      end
+
+      rows, columns = options[:split].split(':').map(&:to_i)
+
+      # Validate ranges
+      if rows < 1 || rows > 99
+        raise ValidationError, "rows must be between 1 and 99, got: #{rows}"
+      end
+
+      if columns < 1 || columns > 99
+        raise ValidationError, "columns must be between 1 and 99, got: #{columns}"
+      end
+
+      # Validate total frames < 1000
+      total_frames = rows * columns
+      if total_frames >= 1000
+        raise ValidationError, "Total frames (#{total_frames}) must be less than 1000"
+      end
+
+      # Store parsed values for later use
+      @split_rows = rows
+      @split_columns = columns
+    end
+
     def check_dependencies!
       checker = DependencyChecker.new(verbose: options[:debug])
       results = checker.check_all
@@ -119,8 +188,8 @@ module RubySpriter
         missing << tool unless results[tool][:available]
       end
 
-      # GIMP only needed for image processing
-      if needs_gimp? && !results[:gimp][:available]
+      # GIMP only needed for scaling and background removal (not for sharpen-only)
+      if needs_gimp_specifically? && !results[:gimp][:available]
         missing << :gimp
       end
 
@@ -137,6 +206,10 @@ module RubySpriter
     end
 
     def needs_gimp?
+      options[:scale_percent] || options[:remove_bg] || options[:sharpen]
+    end
+
+    def needs_gimp_specifically?
       options[:scale_percent] || options[:remove_bg]
     end
 
@@ -168,24 +241,45 @@ module RubySpriter
     end
 
     def execute_video_workflow
-      # Step 1: Convert video to spritesheet
+      # Step 1: Determine output filename
+      desired_output = options[:output] || Utils::FileHelper.spritesheet_filename(options[:video])
+      final_output = Utils::FileHelper.ensure_unique_output(desired_output, overwrite: options[:overwrite])
+
+      # Step 2: Convert video to spritesheet
       video_processor = VideoProcessor.new(options)
       result = video_processor.create_spritesheet(
         options[:video],
-        options[:output] || Utils::FileHelper.spritesheet_filename(options[:video])
+        final_output
       )
 
       working_file = result[:output_file]
+      intermediate_files = []
 
-      # Step 2: Apply GIMP processing if requested
+      # Step 3: Apply GIMP processing if requested
       if needs_gimp?
+        initial_file = working_file
         working_file = process_with_gimp(working_file)
+
+        # Track intermediate files for cleanup (everything except initial and final)
+        if working_file != initial_file
+          intermediate_files = collect_intermediate_files(initial_file, working_file)
+        end
+      end
+
+      # Step 4: Move to final output location if different
+      if final_output != working_file
+        FileUtils.cp(working_file, final_output)
+        # Add the GIMP output to intermediates if it's different from final
+        intermediate_files << working_file unless intermediate_files.include?(working_file)
+        working_file = final_output
       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]
+      # Step 5: Clean up intermediate files
+      cleanup_intermediate_files(intermediate_files)
+
+      # Step 6: Extract individual frames if requested
+      if options[:save_frames]
+        split_frames_from_spritesheet(working_file, result[:columns], result[:rows], result[:frames])
       end
 
       Utils::OutputFormatter.header("SUCCESS!")
@@ -196,16 +290,42 @@ module RubySpriter
 
     def execute_image_workflow
       working_file = options[:image]
+      intermediate_files = []
 
-      # Apply GIMP processing if requested
+      # Apply GIMP processing if requested (GimpProcessor handles uniqueness)
       if needs_gimp?
+        initial_file = working_file
         working_file = process_with_gimp(working_file)
+
+        # Track intermediate files for cleanup (everything except initial and final)
+        if working_file != initial_file
+          intermediate_files = collect_intermediate_files(initial_file, working_file)
+        end
       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]
+      # Move to final output location if user specified explicit --output
+      if options[:output]
+        final_output = Utils::FileHelper.ensure_unique_output(options[:output], overwrite: options[:overwrite])
+        if working_file != final_output
+          FileUtils.cp(working_file, final_output)
+          # Add the GIMP output to intermediates if it's different from final
+          intermediate_files << working_file unless intermediate_files.include?(working_file)
+          working_file = final_output
+        end
+      end
+
+      # Clean up intermediate files
+      cleanup_intermediate_files(intermediate_files)
+
+      # Determine if we should split the image into frames
+      should_split = options[:save_frames] || options[:split]
+
+      if should_split
+        # Determine rows, columns, and frames to use
+        rows, columns, frames = determine_split_parameters(working_file)
+
+        # Split the image into frames
+        split_frames_from_spritesheet(working_file, columns, rows, frames)
       end
 
       Utils::OutputFormatter.header("SUCCESS!")
@@ -220,10 +340,11 @@ module RubySpriter
 
     def execute_consolidate_workflow
       consolidator = Consolidator.new(options)
-      
-      output_file = options[:output] || generate_consolidated_filename
-      
-      result = consolidator.consolidate(options[:consolidate], output_file)
+
+      desired_output = options[:output] || generate_consolidated_filename
+      final_output = Utils::FileHelper.ensure_unique_output(desired_output, overwrite: options[:overwrite])
+
+      result = consolidator.consolidate(options[:consolidate], final_output)
 
       Utils::OutputFormatter.header("SUCCESS!")
       Utils::OutputFormatter.success("Final output: #{result[:output_file]}")
@@ -237,8 +358,57 @@ module RubySpriter
     end
 
     def generate_consolidated_filename
-      timestamp = Time.now.strftime('%Y%m%d_%H%M%S')
-      "consolidated_spritesheet_#{timestamp}.png"
+      "consolidated_spritesheet.png"
+    end
+
+    def split_frames_from_spritesheet(spritesheet_file, columns, rows, frames)
+      # Determine frames directory based on spritesheet filename
+      spritesheet_basename = File.basename(spritesheet_file, '.*')
+      frames_dir = File.join(File.dirname(spritesheet_file), "#{spritesheet_basename}_frames")
+
+      # Split the spritesheet into individual frames
+      splitter = Utils::SpritesheetSplitter.new
+      splitter.split_into_frames(spritesheet_file, frames_dir, columns, rows, frames)
+    end
+
+    def collect_intermediate_files(initial_file, final_file)
+      # Find all files that were created during GIMP processing
+      # Pattern: initial_file + suffixes like -nobg-fuzzy, -scaled-40pct, etc.
+      # Note: output_filename uses DASH separator, not underscore
+      dir = File.dirname(initial_file)
+      basename = File.basename(initial_file, '.*')
+      ext = File.extname(initial_file)
+
+      # Get all PNG files in the directory that start with the basename and have a dash
+      pattern = File.join(dir, "#{basename}-*#{ext}")
+      intermediate_files = Dir.glob(pattern)
+
+      # Normalize paths for comparison (Windows compatibility)
+      initial_normalized = File.expand_path(initial_file)
+      final_normalized = File.expand_path(final_file)
+
+      # Exclude the initial and final files
+      intermediate_files.reject do |f|
+        f_normalized = File.expand_path(f)
+        f_normalized == initial_normalized || f_normalized == final_normalized
+      end
+    end
+
+    def cleanup_intermediate_files(files)
+      return if files.empty?
+
+      if options[:debug]
+        Utils::OutputFormatter.note("Cleaning up #{files.length} intermediate file(s):")
+      end
+
+      files.each do |file|
+        if File.exist?(file)
+          File.delete(file)
+          if options[:debug]
+            Utils::OutputFormatter.indent("Deleted: #{File.basename(file)}")
+          end
+        end
+      end
     end
 
     def cleanup
@@ -247,5 +417,65 @@ module RubySpriter
         Utils::OutputFormatter.note("Cleaned up temporary files") if options[:debug]
       end
     end
+
+    def determine_split_parameters(image_file)
+      metadata = MetadataManager.read(image_file)
+
+      # Check if we have metadata
+      if metadata && metadata[:columns] && metadata[:rows] && metadata[:frames]
+        # Metadata exists
+        if options[:split] && !options[:override_md]
+          # Warn user that split values will be ignored
+          Utils::OutputFormatter.note("Image has metadata (#{metadata[:rows]}×#{metadata[:columns]}). Your --split values will be ignored. Use --override-md to override.")
+          return [metadata[:rows], metadata[:columns], metadata[:frames]]
+        elsif options[:split] && options[:override_md]
+          # Use user's split values
+          frames = @split_rows * @split_columns
+          validate_image_dimensions(image_file, @split_rows, @split_columns)
+          return [@split_rows, @split_columns, frames]
+        else
+          # Use metadata
+          return [metadata[:rows], metadata[:columns], metadata[:frames]]
+        end
+      else
+        # No metadata
+        if options[:split]
+          # Use user's split values
+          frames = @split_rows * @split_columns
+          validate_image_dimensions(image_file, @split_rows, @split_columns)
+          return [@split_rows, @split_columns, frames]
+        else
+          # Error: no metadata and no split option
+          raise ValidationError, "Image has no metadata. Please provide --split R:C"
+        end
+      end
+    end
+
+    def validate_image_dimensions(image_file, rows, columns)
+      # Get image dimensions using ImageMagick
+      cmd = [
+        'magick',
+        'identify',
+        '-format', '%wx%h',
+        Utils::PathHelper.quote_path(image_file)
+      ].join(' ')
+
+      stdout, stderr, status = Open3.capture3(cmd)
+
+      unless status.success?
+        raise ProcessingError, "Could not get image dimensions: #{stderr}"
+      end
+
+      width, height = stdout.strip.split('x').map(&:to_i)
+
+      # Check if dimensions divide evenly
+      unless width % columns == 0
+        raise ValidationError, "Image width (#{width}) not evenly divisible by #{columns} columns"
+      end
+
+      unless height % rows == 0
+        raise ValidationError, "Image height (#{height}) not evenly divisible by #{rows} rows"
+      end
+    end
   end
 end

data/lib/ruby_spriter/utils/file_helper.rb

@@ -51,6 +51,31 @@ module RubySpriter
           validate_exists!(path)
           raise ValidationError, "File not readable: #{path}" unless File.readable?(path)
         end
+
+        # Generate unique filename by adding timestamp if file exists
+        # @param path [String] Original file path
+        # @return [String] Unique file path (adds timestamp if original exists)
+        def unique_filename(path)
+          return path unless File.exist?(path)
+
+          dir = File.dirname(path)
+          ext = File.extname(path)
+          basename = File.basename(path, ext)
+          timestamp = Time.now.strftime('%Y%m%d_%H%M%S_%3N') # Include milliseconds
+
+          File.join(dir, "#{basename}_#{timestamp}#{ext}")
+        end
+
+        # Ensure output filename is unique based on overwrite option
+        # @param path [String] Desired output path
+        # @param overwrite [Boolean] If true, return original path; if false, make unique
+        # @return [String] Output path (unique if overwrite is false and file exists)
+        def ensure_unique_output(path, overwrite: false)
+          return path if overwrite
+          return path unless File.exist?(path)
+
+          unique_filename(path)
+        end
       end
     end
   end