ruby_spriter 0.6.6 → 0.6.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b6e4b3befadf222f9fe4a13b50eb16a5a39124c45f5dad2769f7c4f9153aae4f
-  data.tar.gz: 9f13e8d5da4c706a3d834f5a8d125ee46a1d7f04e5a643c90bda451bdb7f6e9c
+  metadata.gz: 9b62fa9c591b35279199986edc2cf288249c74d80d3479eba177293c53b1dca1
+  data.tar.gz: 71603609b398ec1ac7d0caac7c7194ef0d5e09170a4841e6e3f2f2c0cec65ff7
 SHA512:
-  metadata.gz: 8b05aec242fb65fb3f8745e276f7ec35ce2d05884f62e9b5af8fcef896a8f66ba2050c48d9c6e6c7400ad4ba93215225e5624c04bba25417e32dfff2e255b345
-  data.tar.gz: 97631e37ef5cbe5bb544526d1e696a870dc9cb26759d2838b1af4f77d81e03696f717225f3858ac55bd2a2ecdd3e86dbe6a4e8c91dc4ac8c75f52f7ff1df68e3
+  metadata.gz: 634d8516173fcb9461af2b457003e7661728e0dfbc7ac72904b0d771831e5bb730ccba867fd03fdae86acbde1e525300ad88a367c29c118b5dbb6002332a2e9f
+  data.tar.gz: 5330230b6690fd1aaed69f62bd31e901bb5119ed8fa0a2c07a8e3a6b164b190c230809688d5b5142a254bc231a0fd9ac556ed2a97230f807f061c5be5ba4175c

data/CHANGELOG.md

@@ -12,6 +12,263 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.6.7.1] - 2025-10-24
+
+### 🐧 Linux Support Enhancement Release
+
+#### Added
+- **Linux GIMP 3.x Support**: Full support for GIMP 3.x on Linux via Flatpak
+  - Automatic detection of Flatpak GIMP installation (`flatpak:org.gimp.GIMP`)
+  - Automatic Xvfb integration for completely headless GIMP operation
+  - Virtual display provided by Xvfb eliminates display connection requirement
+  - Flatpak socket isolation (`--nosocket=x11 --nosocket=wayland`) prevents GUI from appearing
+  - Python-fu batch mode works correctly with `python-fu-eval` interpreter
+  - Background removal, scaling, and all GIMP features fully functional
+  - Perfect for desktop use (no GUI distraction) and server environments (CI/CD, Docker, SSH)
+- **GIMP Version Detection**: Detect and report GIMP version (2.x or 3.x)
+  - `Platform.detect_gimp_version(version_output)` - Parse version from `--version` output
+  - `Platform.get_gimp_version(gimp_path)` - Get version from executable or Flatpak
+  - Works with both regular executables and Flatpak installations
+- **Xvfb Dependency Checking**: Added Xvfb to dependency checker (Linux only)
+  - Marked as required on Linux, optional on Windows/macOS
+  - Provides clear installation instructions if missing
+  - Validates availability before GIMP operations
+- **DependencyChecker Version Tracking**: Store and report detected GIMP version
+- **Xvfb Integration**: Transparent Xvfb usage when GIMP Flatpak detected
+  - Command format: `xvfb-run --auto-servernum --server-args='-screen 0 1024x768x24' flatpak run --nosocket=x11 --nosocket=wayland org.gimp.GIMP --no-splash --quit --batch-interpreter=python-fu-eval`
+  - No user configuration required - works automatically
+  - Completely headless - no GUI windows appear on screen
+
+#### Changed
+- **Platform Detection**: Enhanced to detect Flatpak GIMP alongside traditional installations
+- **GimpProcessor**: Updated to support both GIMP 2.x and 3.x APIs (version-aware)
+- **Unix GIMP Execution**: Automatically uses Xvfb with socket isolation for Flatpak installations
+- **Alternative GIMP Paths**: Added `flatpak:org.gimp.GIMP` to Linux search paths
+- **Warning Filters**: Enhanced to filter Xvfb, Wayland, and Flatpak cosmetic warnings
+- **DependencyChecker**: Now supports platform-specific optional dependencies
+
+#### Technical Details
+- **GIMP Flatpak Detection**: Uses `flatpak list --app | grep` to verify installation
+- **Version Parsing**: Regex-based parsing of `GIMP version X.Y.Z` output
+- **Python Interpreter**: Correct name is `python-fu-eval` (not `python-eval`)
+- **Xvfb Flags**:
+  - `--auto-servernum` - Automatically finds free display number
+  - `--server-args='-screen 0 1024x768x24'` - Configures virtual display
+- **Flatpak Socket Isolation**:
+  - `--nosocket=x11` - Prevents access to host X11 display socket
+  - `--nosocket=wayland` - Prevents access to host Wayland display socket
+  - Ensures GIMP runs only in Xvfb virtual display
+- **Platform Module**: New methods for version detection and Flatpak handling
+- **Warning Filtering**: Filters Gdk-WARNING, LibGimp-WARNING, Gimp-Core-WARNING, X11 socket messages
+
+#### Installation Requirements (Linux)
+```bash
+# Ubuntu/Debian
+sudo apt install flatpak xvfb -y
+flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
+flatpak install flathub org.gimp.GIMP -y
+
+# Fedora/RHEL
+sudo dnf install flatpak xorg-x11-server-Xvfb -y
+flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
+flatpak install flathub org.gimp.GIMP -y
+```
+
+#### Example Output
+```bash
+$ ruby_spriter --check-dependencies
+============================================================
+Dependency Check
+============================================================
+
+✅ FFMPEG
+   Found: 6.1.1
+
+✅ FFPROBE
+   Found: 6.1.1
+
+✅ IMAGEMAGICK
+   Found: Version: ImageMagick 6.9.12-98 Q16 x86_64
+
+✅ XVFB
+   Found: Usage: xvfb-run [OPTION ...] COMMAND
+
+✅ GIMP
+   Found: flatpak:org.gimp.GIMP
+   Version: GIMP 3.0.6
+
+============================================================
+
+$ ruby_spriter --image sprite.png --remove-bg
+============================================================
+GIMP Processing
+============================================================
+📝 Using GIMP via Xvfb (virtual display)
+      Removing background (fuzzy select)...
+      === GIMP Messages ===
+      Loading image...
+      Image size: 1280x748
+      Added alpha channel
+      Sampling 4 corners...
+      Using FUZZY SELECT (contiguous regions only)
+        Corner 1 at (0, 0)
+        Corner 2 at (1279, 0)
+        Corner 3 at (0, 747)
+        Corner 4 at (1279, 747)
+      Selection complete
+      Growing selection by 1 pixels...
+      Selection grown
+      Removing background...
+      Background removed
+      Deselecting...
+      Exporting...
+      SUCCESS - Background removed!
+      ====================
+✅ Background Removal complete (142.15 KB)
+```
+
+**Note**: No GIMP GUI window appears on screen - completely headless operation!
+
+---
+
+## [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