ruby_spriter 0.6.6 → 0.6.7.1

data/README.md

@@ -1,4 +1,4 @@
-# Ruby Spriter v0.6.6
+# Ruby Spriter v0.6.7.1
 
 [![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)
@@ -16,11 +16,15 @@ A powerful cross-platform Ruby tool for creating high-quality spritesheets from
 - 🎬 **Video to Spritesheet** - Extract frames from MP4 videos using FFmpeg
 - 🖼️ **Advanced Image Processing** - Scale, sharpen, and remove backgrounds with precision
 - 🎨 **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
+- 📐 **Spritesheet Consolidation** - Merge multiple spritesheets vertically (file list or directory)
+- 📊 **Metadata Management** - Embed, verify, and add grid information to PNG files
+- 🎯 **Frame Extraction** - Extract specific frames by number and create new spritesheets
+- 🏷️ **Metadata Addition** - Add spritesheet metadata to external images
 - 🔒 **Automatic File Protection** - Unique timestamped filenames prevent accidental overwrites (v0.6.6+)
+- 📦 **Batch Processing** - Process multiple MP4 files in a directory automatically (v0.6.7+)
+- 🗜️ **Maximum Compression** - Optimal PNG compression while preserving metadata (v0.6.7+)
 - 🌍 **Cross-Platform** - Works seamlessly on Windows, Linux, and macOS
-- 🧪 **Production Ready** - Comprehensive RSpec test coverage
+- 🧪 **Production Ready** - Comprehensive RSpec test coverage (365 tests)
 
 ### Image Processing Features
 
@@ -64,6 +68,7 @@ A powerful cross-platform Ruby tool for creating high-quality spritesheets from
 | **FFprobe** | Latest | Video analysis (included with FFmpeg) |
 | **ImageMagick** | 7.x+ | Metadata and sharpening |
 | **GIMP** | 3.x (or 2.10) | Scaling and background removal |
+| **Xvfb** | Latest (Linux only) | Virtual display for headless GIMP |
 
 ### Ruby Version
 - Ruby 2.7.0 or higher
@@ -86,22 +91,104 @@ Ruby Spriter requires these external tools for video and image processing:
 | **FFmpeg** | Video frame extraction | Any recent version |
 | **ImageMagick** | Image manipulation & metadata | 7.x or 6.9+ |
 | **GIMP** | Advanced image processing | 3.x (or 2.10) |
+| **Xvfb** | Virtual display (Linux only) | Any recent version |
 
 #### Installing Prerequisites
 
-**Windows (Chocolatey)**
-```powershell
-choco install ffmpeg imagemagick gimp -y
-```
+**Windows (Chocolatey - Recommended)**
+
+Chocolatey is a package manager for Windows that simplifies software installation. If you don't have Chocolatey installed:
+
+1. **Install Chocolatey** (run PowerShell as Administrator):
+   ```powershell
+   Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
+   ```
+
+   Verify installation:
+   ```powershell
+   choco --version
+   ```
+
+2. **Install Ruby** (if not already installed):
+   ```powershell
+   choco install ruby -y
+   ```
+
+   Close and reopen PowerShell, then verify:
+   ```powershell
+   ruby --version
+   gem --version
+   ```
+
+3. **Install Ruby Spriter dependencies**:
+   ```powershell
+   choco install ffmpeg imagemagick gimp -y
+   ```
+
+   This installs all required tools:
+   - **FFmpeg** - Video processing
+   - **ImageMagick** - Image manipulation and metadata
+   - **GIMP** - Advanced image processing
+
+4. **Restart your terminal** to ensure all tools are in your PATH
+
+**Alternative: Manual Installation on Windows**
+
+If you prefer not to use Chocolatey:
+- **Ruby**: Download from [rubyinstaller.org](https://rubyinstaller.org/)
+- **FFmpeg**: Download from [ffmpeg.org](https://ffmpeg.org/download.html)
+- **ImageMagick**: Download from [imagemagick.org](https://imagemagick.org/script/download.php#windows)
+- **GIMP**: Download from [gimp.org](https://www.gimp.org/downloads/)
 
 **macOS (Homebrew)**
+
 ```bash
+# Install Homebrew if not already installed
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+
+# Install Ruby (if not already installed)
+brew install ruby
+
+# Install Ruby Spriter dependencies
 brew install ffmpeg imagemagick gimp
 ```
 
 **Linux (Ubuntu/Debian)**
+
 ```bash
-sudo apt update && sudo apt install ffmpeg imagemagick gimp -y
+# Install Ruby (if not already installed)
+sudo apt update && sudo apt install ruby-full -y
+
+# Install Ruby Spriter dependencies
+sudo apt install ffmpeg imagemagick -y
+
+# Install GIMP 3.x via Flatpak (recommended)
+sudo apt install flatpak -y
+flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
+flatpak install flathub org.gimp.GIMP -y
+
+# Install Xvfb for headless GIMP operation
+sudo apt install xvfb -y
+```
+
+**Note for Linux Users**: GIMP 3.x requires a display connection. Ruby Spriter automatically uses Xvfb (X Virtual Framebuffer) with Flatpak socket isolation to provide a completely headless virtual display. No GIMP GUI windows will appear on your screen - perfect for both desktop use (no distractions) and server environments (CI/CD, Docker, SSH sessions).
+
+**Linux (Fedora/RHEL)**
+
+```bash
+# Install Ruby (if not already installed)
+sudo dnf install ruby -y
+
+# Install Ruby Spriter dependencies
+sudo dnf install ffmpeg imagemagick -y
+
+# Install GIMP 3.x via Flatpak (recommended)
+sudo dnf install flatpak -y
+flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
+flatpak install flathub org.gimp.GIMP -y
+
+# Install Xvfb for headless GIMP operation
+sudo dnf install xorg-x11-server-Xvfb -y
 ```
 
 ---
@@ -135,7 +222,7 @@ bundle install
 
 # Build and install gem locally
 gem build ruby_spriter.gemspec
-gem install ruby_spriter-0.6.6.gem
+gem install ruby_spriter-0.6.7.gem
 ```
 
 **Best for**: Contributors, developers wanting latest code
@@ -210,23 +297,79 @@ ruby_spriter --image sprite.png --remove-bg \
   --threshold 1.5 --grow 2
 ```
 
+### Batch Processing (v0.6.7+)
+```bash
+# Process all videos in a directory
+ruby_spriter --batch --dir "videos/"
+
+# Batch process with scaling and compression
+ruby_spriter --batch --dir "videos/" --scale 50 --max-compress
+
+# Batch process with output to different directory
+ruby_spriter --batch --dir "videos/" --outputdir "output/"
+
+# Batch process and consolidate all results
+ruby_spriter --batch --dir "videos/" --batch-consolidate
+```
+
+### Consolidate Spritesheets
+```bash
+# Consolidate specific files (comma-separated)
+ruby_spriter --consolidate file1.png,file2.png,file3.png
+
+# Consolidate all spritesheets in a directory (v0.6.7+)
+ruby_spriter --consolidate --dir "spritesheets/"
+
+# Consolidate with compression
+ruby_spriter --consolidate --dir "spritesheets/" --max-compress
+```
+
+### Frame Extraction (v0.6.8+)
+```bash
+# Extract specific frames by number
+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
+
+# Extract, process, and save frames
+ruby_spriter --image sprite.png --extract 1,3,5,7 \
+  --scale 50 --sharpen --save-frames
+
+# 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
+```
+
+### Metadata Management (v0.6.8+)
+```bash
+# Add metadata to external spritesheet
+ruby_spriter --image sprite.png --add-meta 4:4
+
+# Add metadata with partial grid (14 frames in 4x4 grid)
+ruby_spriter --image sprite.png --add-meta 4:4 --frames 14
+
+# Replace existing metadata
+ruby_spriter --image existing.png --add-meta 8:8 --overwrite-meta
+
+# Add metadata and copy to new file
+ruby_spriter --image sprite.png --add-meta 4:4 --output sprite_meta.png
+```
+
 ### Advanced Workflows
 ```bash
-# Complete processing pipeline
+# Complete processing pipeline with compression
 ruby_spriter --video input.mp4 \
   --frames 64 --columns 8 \
   --scale 50 --interpolation nohalo \
   --remove-bg \
-  --sharpen --sharpen-gain 0.8
+  --sharpen --sharpen-gain 0.8 \
+  --max-compress
 
 # Process existing image with quality enhancement
 ruby_spriter --image large_sprite.png \
   --scale 50 --interpolation lohalo \
   --sharpen --sharpen-gain 1.2
-
-# Consolidate multiple spritesheets
-ruby_spriter --consolidate file1.png,file2.png,file3.png \
-  --output combined.png
 ```
 
 ---
@@ -239,7 +382,9 @@ ruby_spriter --consolidate file1.png,file2.png,file3.png \
 ```bash
 -v, --video FILE              Input video file (MP4 only)
 -i, --image FILE              Input image file (PNG only)
-    --consolidate FILES       Consolidate multiple spritesheets (PNG only, comma-separated)
+    --batch                   Batch process mode (use with --dir)
+    --dir DIRECTORY           Directory for batch or consolidate operations
+    --consolidate [FILES]     Consolidate spritesheets (comma-separated files or use with --dir)
     --verify FILE             Verify spritesheet metadata (PNG only)
 ```
 
@@ -285,6 +430,34 @@ ruby_spriter --consolidate file1.png,file2.png,file3.png \
 --preset contact              8×? grid, 64 frames, 160px wide
 ```
 
+#### **Batch Processing Options (v0.6.7+)**
+```bash
+    --batch                   Enable batch processing mode
+    --dir DIRECTORY           Directory containing MP4 files to process
+    --outputdir DIRECTORY     Output directory for processed files
+    --batch-consolidate       Consolidate all resulting spritesheets
+```
+
+#### **Compression Options (v0.6.7+)**
+```bash
+    --max-compress            Apply maximum PNG compression (preserves metadata)
+```
+
+#### **Frame Extraction Options (v0.6.8+)**
+```bash
+    --extract FRAMES          Extract specific frames by number (e.g., 1,2,4,5,8)
+    --columns NUM             Output grid columns for extracted spritesheet (default: 4)
+    --save-frames             Keep individual extracted frames on disk
+    --split R:C               Split spritesheet into all individual frames (rows:columns)
+    --override-md             Override embedded metadata when using --split
+```
+
+#### **Metadata Management Options (v0.6.8+)**
+```bash
+    --add-meta R:C            Add spritesheet metadata (rows:columns, e.g., 4:4)
+    --overwrite-meta          Replace existing metadata
+```
+
 #### **Other Options**
 ```bash
     --overwrite               Overwrite existing output files (default: create unique filenames)
@@ -322,11 +495,28 @@ ruby_spriter --video explosion.mp4 \
 
 #### Multiple Character Directions
 ```bash
-# Consolidate walk cycles for 8 directions
+# Consolidate walk cycles for 8 directions (file list)
 ruby_spriter --consolidate \
   walk_n.png,walk_ne.png,walk_e.png,walk_se.png,\
   walk_s.png,walk_sw.png,walk_w.png,walk_nw.png \
   --output character_walk_all.png
+
+# Or consolidate all spritesheets in a directory (v0.6.7+)
+ruby_spriter --consolidate --dir "walk_cycles/" \
+  --output character_walk_all.png
+```
+
+### Batch Processing Workflows (v0.6.7+)
+```bash
+# Process entire animation library
+ruby_spriter --batch --dir "raw_animations/" \
+  --outputdir "game_assets/sprites/" \
+  --scale 50 --remove-bg --sharpen --max-compress
+
+# Create and consolidate multiple character states
+ruby_spriter --batch --dir "character_states/" \
+  --frames 8 --columns 4 \
+  --batch-consolidate
 ```
 
 ### Quality Enhancement
@@ -335,6 +525,7 @@ ruby_spriter --consolidate \
 ruby_spriter --image 4k_sprite.png \
   --scale 25 --interpolation lohalo \
   --sharpen --sharpen-gain 1.0 \
+  --max-compress \
   --output hd_sprite.png
 ```
 
@@ -342,6 +533,91 @@ ruby_spriter --image 4k_sprite.png \
 
 ## 🔧 Advanced Features
 
+### Batch Processing (v0.6.7+)
+
+Process entire directories of MP4 files with consistent settings:
+
+```bash
+# Basic batch processing
+ruby_spriter --batch --dir "animations/"
+# Processes all MP4s with default 4x4 grid
+
+# Batch with processing options
+ruby_spriter --batch --dir "animations/" \
+  --frames 32 --columns 8 \
+  --scale 50 --remove-bg --sharpen \
+  --max-compress
+
+# Batch with output directory
+ruby_spriter --batch --dir "raw_videos/" \
+  --outputdir "game_assets/sprites/"
+
+# Batch and consolidate results
+ruby_spriter --batch --dir "character_states/" \
+  --batch-consolidate \
+  --output character_complete.png
+```
+
+**Features:**
+- Automatically finds all MP4 files in directory
+- Applies consistent processing to all videos
+- Enforces unique output filenames (unless `--overwrite`)
+- Continues processing if one file fails
+- Optional consolidation of all results
+- Supports all video and image processing options
+
+### Maximum Compression (v0.6.7+)
+
+Reduce file sizes while preserving metadata:
+
+```bash
+# Compress during video processing
+ruby_spriter --video input.mp4 --max-compress
+
+# Compress during image processing
+ruby_spriter --image sprite.png --scale 50 --max-compress
+
+# Compress batch output
+ruby_spriter --batch --dir "videos/" --max-compress
+
+# Compress consolidated output
+ruby_spriter --consolidate --dir "sprites/" --max-compress
+```
+
+**Compression Details:**
+- Uses ImageMagick optimal PNG compression settings
+- Compression level 9 (maximum zlib)
+- Paeth filter (compression filter 5)
+- Filtered strategy (compression strategy 1)
+- Quality 95
+- Preserves embedded spritesheet metadata
+- Displays size reduction statistics
+
+### Directory-Based Consolidation (v0.6.7+)
+
+Consolidate all spritesheets in a directory automatically:
+
+```bash
+# Scan directory and consolidate all spritesheets
+ruby_spriter --consolidate --dir "character_animations/"
+
+# With output directory
+ruby_spriter --consolidate --dir "sprites/" \
+  --outputdir "final_assets/"
+
+# With compression
+ruby_spriter --consolidate --dir "sprites/" \
+  --max-compress \
+  --output character_complete.png
+```
+
+**Directory Mode Features:**
+- Automatically scans for PNG files with metadata
+- Filters out non-spritesheet images
+- Sorts files alphabetically before consolidation
+- Requires at least 2 valid spritesheets
+- Cannot mix with comma-separated file list mode
+
 ### 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:
@@ -429,16 +705,45 @@ ruby_spriter --video input.mp4 --scale 50 --sharpen --debug
 # - Processing timestamps
 ```
 
+### Headless Linux Operation (v0.6.7.1+)
+
+Ruby Spriter provides completely headless GIMP operation on Linux via Xvfb and Flatpak socket isolation:
+
+```bash
+# No GIMP GUI appears during processing
+ruby_spriter --image sprite.png --remove-bg --scale 50
+
+# Perfect for server environments
+ruby_spriter --batch --dir "sprites/" --remove-bg --max-compress
+```
+
+**How it Works:**
+- Automatically detects GIMP 3.x Flatpak installation
+- Uses Xvfb (X Virtual Framebuffer) to provide virtual display
+- Flatpak socket isolation (`--nosocket=x11 --nosocket=wayland`) prevents GUI from appearing
+- No configuration required - works automatically
+
+**Use Cases:**
+- **Desktop**: No GUI distractions during batch processing
+- **Server**: Headless automation on Ubuntu Server, CI/CD pipelines
+- **Docker**: Run in containers without display server
+- **SSH**: Process sprites remotely without X forwarding
+
+**Requirements:**
+- GIMP 3.x via Flatpak (`flatpak install flathub org.gimp.GIMP`)
+- Xvfb (`sudo apt install xvfb` on Ubuntu/Debian)
+
 ---
 
 ## 🏗️ Architecture
 
-### Four Processing Modes
+### Five Processing Modes
 
 1. **Video Mode** - MP4 → Spritesheet → Optional Processing
 2. **Image Mode** - PNG → Processing → Enhanced PNG
-3. **Consolidate Mode** - Multiple PNGs → Combined Spritesheet
-4. **Verify Mode** - Read and display embedded metadata
+3. **Consolidate Mode** - Multiple PNGs → Combined Spritesheet (file list or directory)
+4. **Batch Mode** (v0.6.7+) - Directory of MP4s → Multiple Spritesheets → Optional Consolidation
+5. **Verify Mode** - Read and display embedded metadata
 
 ### Processing Pipeline
 
@@ -472,7 +777,9 @@ Output PNG with Metadata
 
 **Consolidate Mode:**
 ```
-Multiple Input PNGs
+Multiple Input PNGs (file list or directory scan)
+    ↓
+[Metadata Filter] Find PNGs with spritesheet metadata (directory mode)
     ↓
 [ImageMagick] Read Metadata from Each
     ↓
@@ -482,15 +789,36 @@ Multiple Input PNGs
     ↓
 [ImageMagick] Embed Combined Metadata
     ↓
+[ImageMagick] Optional Max Compression
+    ↓
 Output Consolidated PNG
 ```
 
+**Batch Mode (v0.6.7+):**
+```
+Directory of MP4 Files
+    ↓
+[Scan] Find all MP4 files
+    ↓
+[Loop] For each MP4:
+    ├─ [FFmpeg] Extract frames + create spritesheet
+    ├─ [GIMP] Optional scaling/background removal
+    ├─ [ImageMagick] Optional sharpening
+    └─ [ImageMagick] Optional max compression
+    ↓
+[Optional] Consolidate all results with --batch-consolidate
+    ↓
+Multiple Output PNGs (or one consolidated PNG)
+```
+
 ### Key Components
 
 - **Processor** - Main orchestration
 - **VideoProcessor** - FFmpeg integration
 - **GimpProcessor** - GIMP batch scripting
-- **Consolidator** - Multi-sheet merging
+- **Consolidator** - Multi-sheet merging (file list or directory)
+- **BatchProcessor** (v0.6.7+) - Directory batch processing
+- **CompressionManager** (v0.6.7+) - PNG compression with metadata preservation
 - **MetadataManager** - PNG metadata handling
 - **DependencyChecker** - Tool detection
 - **Platform** - Cross-platform abstraction
@@ -531,12 +859,17 @@ ruby-spriter/
 │       ├── video_processor.rb
 │       ├── gimp_processor.rb
 │       ├── consolidator.rb
+│       ├── batch_processor.rb        # v0.6.7+
+│       ├── compression_manager.rb    # v0.6.7+
 │       ├── metadata_manager.rb
 │       ├── dependency_checker.rb
 │       ├── platform.rb
 │       └── utils/            # Helper modules
-├── spec/                     # RSpec tests
+├── spec/                     # RSpec tests (313 examples)
+├── .claude/
+│   └── agents/               # Custom Claude Code agent config
 ├── CLAUDE.md                 # Developer documentation
+├── CHANGELOG.md              # Version history
 └── README.md                 # This file
 ```
 
@@ -554,15 +887,33 @@ bundle exec ruby_spriter --video test.mp4
 
 ## 🤝 Contributing
 
-Contributions are welcome! Please:
-
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Write tests for your changes
-4. Ensure all tests pass (`bundle exec rspec`)
-5. Commit your changes (`git commit -m 'Add amazing feature'`)
-6. Push to the branch (`git push origin feature/amazing-feature`)
-7. Open a Pull Request
+Contributions are welcome! This project follows strict **Test-Driven Development (TDD)** practices.
+
+### Development Workflow
+
+1. **Fork the repository**
+2. **Create a feature branch** (`git checkout -b feature/amazing-feature`)
+3. **Follow TDD Red-Green-Refactor cycle:**
+   - ✅ **Red**: Write ONE test → Run it → Verify it FAILS
+   - ✅ **Green**: Write minimal code → Run test → Verify it PASSES
+   - ✅ **Refactor**: Clean up → Run all tests → Verify still passing
+   - ✅ **Repeat** for each new test
+4. **Ensure all tests pass** (`bundle exec rspec`)
+5. **Update documentation** (README.md, CHANGELOG.md, CLAUDE.md)
+6. **Commit your changes** (`git commit -m 'Add amazing feature'`)
+7. **Push to the branch** (`git push origin feature/amazing-feature`)
+8. **Open a Pull Request**
+
+### Agent Configuration
+
+This project includes a custom Claude Code agent (`.claude/agents/ruby-spriter-architect.md`) that enforces:
+- Strict TDD (Red-Green-Refactor) workflow
+- Architecture consistency
+- Documentation maintenance
+- Cross-platform compatibility
+- Test coverage requirements
+
+The agent configuration is version-controlled and shared across the team.
 
 ---