Refactor: CLI, auto-detection of format and dimensions, conversion of entire directories

[josephbergdoll]

Overview

This pull request significantly improves the OVG image format conversion tools, transforming them into robust, user-friendly command-line tools with advanced features.

Key Improvements

🚀 New Features

Command-Line Interface

• Proper argument parsing with argparse
• Help system with --help for all commands
• No more manual editing of variables in scripts

Automatic Format Detection

• Detects RLE-compressed vs raw RGBA formats automatically
• Handles both traditional OVG files and raw pixel data
• Smart analysis of file structure and patterns

Smart Dimension Detection

• Multiple strategies for finding correct image dimensions
• Perfect square detection for raw RGBA files
• Factor analysis with scoring for optimal dimensions
• Common resolution detection (160, 200, 240, 256, 320, 400, 480, 640, 800, 1024)

Interactive Size Discovery

• Built-in tool for finding correct dimensions visually
• Step-through different sizes with immediate feedback
• Jump to specific widths for faster discovery
• Customizable range and step size

Batch Processing

• Convert entire directories of files
• Custom file patterns (e.g., *clock*.bin)
• Progress reporting and error handling

Roundtrip Testing

• Built-in testing to verify conversion accuracy
• File size comparison and compression analysis
• Automatic cleanup of test files

🔧 Technical Improvements

Enhanced Compression

• Better RLE compression algorithms
• Improved handling of transparency
• More efficient encoding for PNG to OVG conversion

Robust Error Handling

• Comprehensive error messages
• Graceful handling of malformed files
• Detailed progress reporting

Backward Compatibility

• All existing OVG files work unchanged
• Old scripts preserved as *_old.py for reference
• Same output formats and quality

📚 Documentation

Complete README Rewrite

• Comprehensive usage examples
• Step-by-step workflows
• Troubleshooting guide
• Technical details and specifications

Usage Examples

# Basic conversion with auto-detection
python3 ovg_to_png.py input.bin

# Specify dimensions
python3 ovg_to_png.py input.bin --width 286 --height 286

# Interactive size discovery
python3 ovg_to_png.py input.bin --discover

# Batch directory conversion
python3 ovg_to_png.py input_dir --output-dir output_dir

# PNG to OVG with custom output
python3 png_to_ovg.py my_clock.png clock_new.bin

# Test roundtrip conversion
python3 png_to_ovg.py --test input.bin

Benefits

For Users

• Easier to Use: No more editing variables in scripts
• More Reliable: Automatic detection reduces errors
• Better Discovery: Interactive tools help find correct dimensions
• Batch Processing: Convert multiple files efficiently
• Better Documentation: Clear examples and troubleshooting

For Developers

• Maintainable Code: Proper structure and error handling
• Extensible: Easy to add new features
• Testable: Built-in testing capabilities
• Well Documented: Clear code comments and README

Migration Guide

From Old Scripts

The old scripts required editing variables:

filename = "mex_ovg"
width = 39
height = 39

Now use command-line arguments:

python3 ovg_to_png.py mex_ovg.bin --width 39 --height 39

Backward Compatibility

• Old files renamed to *_old.py for reference
• All existing workflows continue to work
• New features are optional and don't break existing usage

Testing

The new tools have been tested with:

• Original OVG files from the repository
• Various image dimensions and formats
• Roundtrip conversion accuracy
• Batch processing capabilities
• Error handling scenarios

Files Changed

• ovg_to_png.py → Enhanced with CLI and auto-detection
• png_to_ovg.py → Enhanced with CLI and better compression
• README.md → Complete rewrite with comprehensive documentation
• ovg_to_png_old.py → Original script preserved
• png_to_ovg_old.py → Original script preserved

Breaking Changes

None - All existing functionality is preserved. The new tools are drop-in replacements that provide enhanced features while maintaining full backward compatibility.

[cr3ative]

Certainly! Why not! All hail AI. Thank you, this is likely significantly more usable.