ruby_spriter 0.6.5 → 0.6.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f794b569ca3be84a3e33923a645ee3f98a8771d12d1e9befc5bc9f63241d079d
-  data.tar.gz: b8e2078fa01d7095ec071c83e6d0e17683f86b2653a8f610b50925084e9d4984
+  metadata.gz: 1cec402c211c4204134f1a9cf6974093c3e36fd46a45301282260454c91ff33d
+  data.tar.gz: 0de0714668911755bc80ac6f0841d4aa2034f03797dcf027ef6a61e495f46936
 SHA512:
-  metadata.gz: 7fea2f1769c71ae55b040b41c6f1dd29f8d1c384eda0606464fee0c26892d48463586f541a484395c3368170484028488bc3bc6b7f1820f20132ec004fc5ae81
-  data.tar.gz: a751cdce97247fc81627bb3a0d4628c5c560885ce4df8eed744c9923bdd8cb86842c07363e02cc66ff94f2792ff8a50504b980ba7035e559014e1bc24f692985
+  metadata.gz: 71bbe470ac06aaa1acadf00fba48b911daa6f803010a0e88145a46847078e2db3db25cdeb4462ada7a74e9711b7b36c4b706a36bbd9f04ff53af2087a1882434
+  data.tar.gz: f5f092588802ce4402fe952370f17ba76f59543cdd99b24e83f845e1ca2b2a5cc813481909180ac418d2f34f65dcb4ae5a828794e40abd3164a004ef6695235d

data/CHANGELOG.md

@@ -12,6 +12,194 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.6.7] - 2025-10-24
+
+### 🚀 Batch Processing, Compression, Directory Consolidation & Frame Extraction Release
+
+#### Added
+- **Batch Processing Mode** (`--batch`): Process multiple MP4 files in a directory (Issue #16)
+  - `--dir DIRECTORY`: Specify directory containing MP4 files to process
+  - `--outputdir DIRECTORY`: Optional output directory (defaults to input directory)
+  - `--batch-consolidate`: Automatically consolidate all resulting spritesheets
+  - Supports all existing processing options: `--scale`, `--remove-bg`, `--sharpen`, `--interpolation`, etc.
+  - Enforces unique filenames unless `--overwrite` is specified
+  - Continues processing remaining videos if one fails
+  - Provides detailed summary of successes and failures
+- **Maximum Compression** (`--max-compress`): Apply maximum PNG compression (Issue #14)
+  - Uses ImageMagick with optimal compression settings (level 9, filter 5, strategy 1, quality 95)
+  - Preserves embedded metadata through compression
+  - Works with all processing modes: `--video`, `--image`, `--batch`, `--consolidate`
+  - Displays compression statistics (original size, compressed size, savings, reduction percentage)
+- **Directory-Based Consolidation**: `--consolidate` now supports `--dir` option to automatically consolidate all spritesheets in a directory
+  - Scans directory for PNG files with embedded spritesheet metadata
+  - Automatically filters out non-spritesheet PNG files
+  - Sorts files alphabetically by filename before consolidation
+  - Requires at least 2 valid spritesheets in directory
+  - Works with all existing consolidation options: `--output`, `--outputdir`, `--overwrite`, `--max-compress`, `--no-validate-columns`
+  - Mutual exclusivity validation: Cannot use both comma-separated file list and `--dir` with `--consolidate`
+- **Enhanced Context-Sensitive Help System**: Mode-specific help displays only relevant options
+  - `ruby_spriter --video --help`: Shows video mode options (spritesheet generation, processing, output)
+  - `ruby_spriter --image --help`: Shows image mode options (processing, frame extraction, output)
+  - `ruby_spriter --consolidate --help`: Shows consolidation options (input methods, validation, output)
+  - `ruby_spriter --batch --help`: Shows batch processing options (directory processing, applied options)
+  - `ruby_spriter --split --help`: Shows frame extraction options (split format, metadata behavior, output)
+  - General `--help`: Shows mode-specific help hints and directs users to detailed help
+  - **Parent-Child Option Hierarchy**: Visual hierarchy (└─) shows modifier options grouped under parent options
+    - `--interpolation`, `--sharpen*` modifiers shown under `--scale`
+    - `--fuzzy`, `--threshold`, `--grow` modifiers shown under `--remove-bg`
+    - `--override-md` modifier shown under `--split`
+    - `--validate-columns` modifier shown under `--consolidate --dir`
+  - Organized by function (Image Processing, Output Options) instead of by tool (GIMP Processing Options)
+- **Frame Extraction** (`--extract`): Extract specific frames and create new spritesheet
+  - `--extract FRAMES`: Comma-separated frame numbers (e.g., `1,2,4,5,8`)
+  - `--columns NUM`: Specify output grid columns (default: 4)
+  - Supports duplicate frame numbers for animation sequences
+  - 1-indexed frame numbering (left-to-right, top-to-bottom)
+  - Requires spritesheet metadata (works with `--verify` output)
+  - Works with all `--image` processing options: `--scale`, `--remove-bg`, `--sharpen`, `--max-compress`
+  - Automatic output naming with `_extracted` suffix or custom via `--output`
+  - Temporary frames deleted after reassembly unless `--save-frames` specified
+  - Minimum 2 frames required
+  - Out-of-bounds validation against spritesheet metadata
+  - Mutual exclusivity with `--split`
+- **Metadata Management** (`--add-meta`): Add spritesheet metadata to images without metadata
+  - `--add-meta R:C`: Specify grid layout (rows:columns, e.g., `4:4`)
+  - `--overwrite-meta`: Replace existing metadata
+  - `--frames COUNT`: Custom frame count for partial grids (fewer frames than grid size)
+  - In-place modification by default (respects `--overwrite` flag)
+  - Optional `--output` for copying to new file
+  - Dimension validation: Image dimensions must divide evenly by grid
+  - Enables `--extract`, `--consolidate`, `--verify`, `--split` on external spritesheets
+  - Standalone mode: Cannot combine with `--scale`, `--remove-bg`, `--sharpen`
+- **Enhanced `--save-frames`**: Now works with both `--video` and `--extract`
+- **New Modules**:
+  - `BatchProcessor` (lib/ruby_spriter/batch_processor.rb): Orchestrates batch video processing
+  - `CompressionManager` (lib/ruby_spriter/compression_manager.rb): Handles PNG compression with metadata preservation
+- **New Public Method**: `Consolidator#find_spritesheets_in_directory(directory)` for directory scanning
+- **Comprehensive Test Coverage**: 68 new tests (13 for BatchProcessor, 11 for CompressionManager, 15 for directory consolidation, 7 for context-sensitive help, 22 for frame extraction and metadata management)
+
+#### Changed
+- **CLI**: Updated `--consolidate` description to mention `--dir` option
+- **CLI**: Renamed "GIMP Processing Options" to "Processing Options" for tool-agnostic organization
+- **CLI**: Updated image mode help with Frame Extraction & Reassembly section
+- **CLI**: Added Metadata Management section to image mode help
+- **Processor**: Refactored consolidation workflow to support both file list and directory modes
+- **Test Suite**: Increased from 274 to 365 examples (all passing), 75.8% line coverage
+- **CLI**: Added parent-child visual hierarchy to all context-sensitive help displays
+- **CLI**: Corrected `--sharpen` to show as standalone option (not under `--scale`)
+
+#### Examples
+```bash
+# Get context-sensitive help for specific modes
+ruby_spriter --video --help
+ruby_spriter --image --help
+ruby_spriter --consolidate --help
+ruby_spriter --batch --help
+ruby_spriter --split --help
+
+# Process all videos in directory
+ruby_spriter --batch --dir "videos/"
+
+# Process with output to different directory
+ruby_spriter --batch --dir "videos/" --outputdir "output/"
+
+# Process and consolidate all results
+ruby_spriter --batch --dir "videos/" --batch-consolidate
+
+# Process with scaling and compression
+ruby_spriter --batch --dir "videos/" --scale 50 --max-compress
+
+# Compress video output
+ruby_spriter --video "input.mp4" --max-compress
+
+# Compress image processing output
+ruby_spriter --image "sprite.png" --scale 50 --max-compress
+
+# Directory-based consolidation
+ruby_spriter --consolidate --dir "spritesheets/"
+ruby_spriter --consolidate --dir "spritesheets/" --outputdir "output/"
+ruby_spriter --consolidate --dir "spritesheets/" --max-compress
+
+# File list consolidation still works
+ruby_spriter --consolidate file1.png,file2.png,file3.png
+
+# Extract specific frames and create new spritesheet
+ruby_spriter --image sprite.png --extract 1,2,4,5,8 --columns 3
+
+# Extract with duplicates for animation loops
+ruby_spriter --image sprite.png --extract 1,1,2,2,3,3 --save-frames
+
+# Extract and process
+ruby_spriter --image sprite.png --extract 1,3,5,7 --scale 50 --sharpen
+
+# Add metadata to external spritesheet
+ruby_spriter --image sprite.png --add-meta 4:4
+
+# Add metadata with partial grid
+ruby_spriter --image sprite.png --add-meta 4:4 --frames 14 --output sprite_meta.png
+
+# Replace existing metadata
+ruby_spriter --image existing.png --add-meta 8:8 --overwrite-meta
+
+# Workflow: Add metadata, then extract frames
+ruby_spriter --image external.png --add-meta 4:4
+ruby_spriter --image external.png --extract 1,5,9,13 --columns 2
+```
+
+Closes #14, #16
+
+---
+
+## [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