{"id":30838826,"url":"https://github.com/dmtrkovalenko/odiff-cross","last_synced_at":"2025-09-06T18:12:38.902Z","repository":{"id":313496372,"uuid":"1051627344","full_name":"dmtrKovalenko/odiff-cross","owner":"dmtrKovalenko","description":null,"archived":false,"fork":false,"pushed_at":"2025-09-06T13:11:26.000Z","size":76377,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-06T13:29:37.022Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dmtrKovalenko.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-06T11:52:04.000Z","updated_at":"2025-09-06T13:11:30.000Z","dependencies_parsed_at":"2025-09-06T13:39:43.612Z","dependency_job_id":null,"html_url":"https://github.com/dmtrKovalenko/odiff-cross","commit_stats":null,"previous_names":["dmtrkovalenko/odiff-cross"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/dmtrKovalenko/odiff-cross","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmtrKovalenko%2Fodiff-cross","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmtrKovalenko%2Fodiff-cross/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmtrKovalenko%2Fodiff-cross/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmtrKovalenko%2Fodiff-cross/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dmtrKovalenko","download_url":"https://codeload.github.com/dmtrKovalenko/odiff-cross/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmtrKovalenko%2Fodiff-cross/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273941527,"owners_count":25195104,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-06T02:00:13.247Z","response_time":2576,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-06T18:12:33.735Z","updated_at":"2025-09-06T18:12:38.881Z","avatar_url":"https://github.com/dmtrKovalenko.png","language":"Zig","funding_links":[],"categories":[],"sub_categories":[],"readme":"# zdiff\n\nA fast pixel-by-pixel image comparison tool written in Zig. This is a faithful port of [odiff](https://github.com/dmtrKovalenko/odiff) from OCaml to Zig, maintaining full compatibility with the original API while leveraging Zig's performance and safety features.\n\n## Features\n\n- **Fast pixel-by-pixel image comparison** using perceptually accurate color difference algorithms\n- **Antialiasing detection** to ignore antialiased pixels in comparisons\n- **Multiple image format support** (PNG, JPEG, TIFF) via C FFI\n- **Flexible output options** including diff masks and parseable output\n- **Ignore regions** to exclude specific areas from comparison\n- **Memory efficient** with configurable RAM usage optimization\n- **Full CLI compatibility** with the original odiff\n\n## Algorithm Details\n\n### Color Difference Calculation\nzdiff uses the YIQ color space for perceptually accurate color difference calculations:\n\n- **YIQ Color Space**: Converts RGB to YIQ (luminance and chrominance) for better human perception matching\n- **Semi-transparent Pixel Blending**: Properly handles alpha channel by blending with white background\n- **Configurable Threshold**: Allows fine-tuning of sensitivity (0.0-1.0 range)\n\n### Antialiasing Detection\nThe antialiasing detection algorithm identifies edge pixels that may appear different due to antialiasing:\n\n- **Neighbor Analysis**: Examines 3x3 pixel neighborhoods around each different pixel\n- **Brightness Delta Calculation**: Uses brightness differences to identify edge pixels\n- **Sibling Counting**: Counts similar pixels in neighborhoods to detect antialiasing patterns\n- **Cross-Image Validation**: Verifies antialiasing patterns exist in both images\n\n## Installation\n\n### Prerequisites\n- Zig 0.14.1 or later\n- Standard C library (for image format support)\n\n### Building from Source\n```bash\ngit clone \u003crepository-url\u003e\ncd zdiff\nzig build\n```\n\nThe binary will be available at `zig-out/bin/zdiff`.\n\n## Usage\n\n### Basic Usage\n```bash\n# Compare two images\nzdiff image1.png image2.png\n\n# Compare and save diff output\nzdiff image1.png image2.png diff.png\n\n# Compare with custom threshold\nzdiff image1.png image2.png -t 0.05\n\n# Compare with antialiasing detection\nzdiff image1.png image2.png --antialiasing\n```\n\n### Command Line Options\n\n| Option | Description |\n|--------|-------------|\n| `-t, --threshold \u003cvalue\u003e` | Color difference threshold (0.0-1.0, default: 0.1) |\n| `--diff-mask` | Output only changed pixels over transparent background |\n| `--fail-on-layout` | Fail if image dimensions differ |\n| `--parsable-stdout` | Machine-readable output format |\n| `--diff-color \u003chex\u003e` | Color for highlighting differences (e.g., #cd2cc9) |\n| `--aa, --antialiasing` | Ignore antialiased pixels in diff |\n| `--output-diff-lines` | Output line numbers with differences |\n| `--reduce-ram-usage` | Use less memory (slower) |\n| `-i, --ignore \u003cregions\u003e` | Ignore regions (format: x1:y1-x2:y2,x3:y3-x4:y4) |\n| `-h, --help` | Show help message |\n| `--version` | Show version |\n\n### Exit Codes\n- `0` - Images match\n- `21` - Layout difference (when --fail-on-layout is used)\n- `22` - Pixel differences found\n\n### Examples\n\n#### Compare with ignore regions\n```bash\nzdiff image1.png image2.png -i \"10:10-50:50,100:100-200:200\"\n```\n\n#### Parseable output for CI/CD\n```bash\nzdiff image1.png image2.png --parsable-stdout\n# Output: number of different pixels or \"layout\" for dimension mismatch\n```\n\n#### Antialiasing-aware comparison\n```bash\n# Ignore antialiased pixels (useful for font rendering comparisons)\nzdiff text1.png text2.png --antialiasing\n```\n\n## Architecture\n\n### Core Components\n\n1. **Image I/O** (`src/image_io.zig`)\n   - Abstraction layer over C image libraries\n   - Support for PNG, JPEG, and TIFF formats\n   - Memory-safe wrappers around C FFI\n\n2. **Diff Algorithm** (`src/diff.zig`)\n   - Core pixel comparison logic\n   - YIQ color space conversion\n   - Difference calculation and thresholding\n\n3. **Antialiasing Detection** (`src/antialiasing.zig`)\n   - Sophisticated edge detection\n   - Neighborhood analysis\n   - Cross-image pattern validation\n\n4. **Color Delta** (`src/color_delta.zig`)\n   - Perceptual color difference calculations\n   - Alpha blending with white background\n   - YIQ color space transformations\n\n5. **CLI Interface** (`src/cli.zig`)\n   - Command-line argument parsing\n   - Compatible with original odiff API\n   - Comprehensive help and error messages\n\n6. **C Bindings** (`c_bindings/`)\n   - FFI layer for image format support\n   - Memory management for C structures\n   - Placeholder implementations (can be extended with full libpng/libjpeg/libtiff)\n\n### Memory Management\n- **RAII Pattern**: All resources automatically cleaned up via Zig's defer mechanism\n- **Arena Allocators**: Efficient memory allocation patterns\n- **C Interop**: Safe wrappers around C memory management\n\n## Compatibility with odiff\n\nzdiff maintains full API compatibility with the original odiff:\n\n- **Same command-line arguments and flags**\n- **Identical exit codes**\n- **Same output formats**\n- **Compatible ignore region syntax**\n- **Equivalent algorithmic behavior**\n\nThis makes zdiff a drop-in replacement for odiff in existing scripts and CI/CD pipelines.\n\n## Performance\n\nzdiff is designed for performance:\n\n- **Compiled to native code** via Zig's LLVM backend\n- **Zero-cost abstractions** with compile-time optimization\n- **Memory-efficient algorithms** with configurable RAM usage\n- **SIMD potential** for future vectorization optimizations\n\n## Development\n\n### Project Structure\n```\nzdiff/\n├── src/\n│   ├── main.zig           # CLI entry point\n│   ├── root.zig           # Library exports\n│   ├── image_io.zig       # Image loading/saving\n│   ├── diff.zig           # Core diff algorithm\n│   ├── antialiasing.zig   # Antialiasing detection\n│   ├── color_delta.zig    # Color difference calculation\n│   ├── cli.zig           # Command-line interface\n│   └── c_bindings.zig    # C FFI wrappers\n├── c_bindings/\n│   ├── zdiff_io.h        # C header definitions\n│   └── zdiff_io.c        # C implementation (placeholder)\n├── build.zig             # Build configuration\n└── README.md\n```\n\n### Building and Testing\n```bash\n# Build debug version\nzig build\n\n# Build optimized release\nzig build -Doptimize=ReleaseFast\n\n# Run tests\nzig build test\n\n# Run with arguments\nzig build run -- image1.png image2.png\n```\n\n### Extending Image Format Support\n\nTo add support for additional image formats:\n\n1. Implement C functions in `c_bindings/zdiff_io.c`\n2. Add format detection in `src/image_io.zig`\n3. Create wrapper functions in `src/c_bindings.zig`\n4. Update build.zig to link required libraries\n\n## Future Enhancements\n\n- **Full image library integration** (replace placeholder C implementations)\n- **SIMD optimizations** for faster pixel processing\n- **Parallel processing** for large images\n- **Additional output formats** (JSON, XML)\n- **Web Assembly target** for browser usage\n- **Integration with zig-cli library** for better argument parsing\n\n## License\n\nThis project maintains the same license as the original odiff project.\n\n## Contributing\n\nContributions are welcome! Please ensure:\n\n- Code follows Zig formatting conventions\n- All tests pass\n- New features include appropriate tests\n- Documentation is updated for API changes\n\n## Acknowledgments\n\n- Original [odiff](https://github.com/dmtrKovalenko/odiff) project by Dmitriy Kovalenko\n- The Zig programming language community\n- Contributors to the image processing libraries used","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdmtrkovalenko%2Fodiff-cross","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdmtrkovalenko%2Fodiff-cross","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdmtrkovalenko%2Fodiff-cross/lists"}