# jpegli-rs Examples
Tools for debugging, benchmarking, and validating the jpegli-rs encoder/decoder.
## Quick Reference
| `jpeg_inspect` | JPEG structure analysis & validation | `cargo run --release --example jpeg_inspect -- image.jpg` |
| `quality_compare` | Compare encoder quality/size | `cargo run --release --example quality_compare -- image.png` |
| `test_libjpeg_compat` | Verify libjpeg compatibility | `cargo run --release --example test_libjpeg_compat` |
| `benchmark_sharp_yuv` | Encoder throughput benchmarks | `cargo run --release --example benchmark_sharp_yuv` |
| `low_q_report` | HTML quality report (Rust vs C++) | `cargo run --release --example low_q_report --features test-utils` |
## JPEG Inspection & Validation
### jpeg_inspect
Comprehensive JPEG analysis tool. Analyzes markers, quantization tables, Huffman tables,
progressive scans, and validates decoding with multiple decoders.
```bash
# Quick overview
cargo run --release --example jpeg_inspect -- image.jpg
# Detailed analysis
cargo run --release --example jpeg_inspect -- --all image.jpg
# Validate with multiple decoders (zune-jpeg, jpegli-rs, mozjpeg)
cargo run --release --example jpeg_inspect -- --validate image.jpg
# Batch validate all JPEGs in a directory
cargo run --release --example jpeg_inspect -- --validate /path/to/jpgs/
# Analyze quantization tables
cargo run --release --example jpeg_inspect -- --quant image.jpg
# Analyze Huffman tables
cargo run --release --example jpeg_inspect -- --huffman image.jpg
# Analyze progressive scan structure
cargo run --release --example jpeg_inspect -- --scans progressive.jpg
# Compare two JPEGs
cargo run --release --example jpeg_inspect -- --compare other.jpg image.jpg
```
## Quality & Performance Testing
### quality_compare
Compare encoder quality metrics (DSSIM, SSIMULACRA2, Butteraugli) and file sizes.
```bash
# Single quality level
cargo run --release --example quality_compare -- --quality 80 --encoder jpegli-rs-ycbcr image.png
# Compare multiple encoders
cargo run --release --example quality_compare -- --encoder jpegli-rs-xyb --metric all image.png
# Sweep quality levels for Pareto curve
cargo run --release --example quality_compare -- --pareto image.png
# Available encoders: jpegli-rs-ycbcr, jpegli-rs-xyb, cmozjpeg
# Available metrics: dssim, ssim2, butteraugli, all
```
### benchmark_sharp_yuv
Encoder throughput benchmarks at various resolutions.
```bash
cargo run --release --example benchmark_sharp_yuv
# Output: MP/s throughput for 512x512, 1080p, 4K resolutions
```
### low_q_report
Generate HTML report comparing Rust vs C++ jpegli at low quality levels.
```bash
cargo run --release --example low_q_report --features test-utils
# Output: reports/low_q_report.html
```
## XYB Debugging Tools
XYB color space is the primary focus for quality improvement. These tools help debug
the ~5 SSIMULACRA2 quality gap between Rust and C++ XYB encoding.
### xyb_parity_test
Compare Rust vs C++ jpegli XYB output (file size and DSSIM).
```bash
cargo run --release --example xyb_parity_test
# Compares multiple Kodak images at Q70/80/90
# Shows size difference and DSSIM delta
```
### xyb_cpp_comparison
Detailed comparison of Rust vs C++ XYB encoding with Butteraugli metrics.
```bash
cargo run --release --example xyb_cpp_comparison
# Shows: quality level, file sizes, butteraugli scores
```
### xyb_vs_ycbcr_butteraugli
Compare XYB vs YCbCr encoding quality using Butteraugli metric.
```bash
cargo run --release --example xyb_vs_ycbcr_butteraugli
# Shows butteraugli scores for XYB vs YCbCr at each quality level
# Lower butteraugli = better quality
```
### xyb_ulp_parity
Test XYB color conversion precision (ULP = units in last place).
```bash
cargo run --release --example xyb_ulp_parity
# Shows max/mean error per XYB channel
# Verifies Rust XYB matches C++ at floating-point precision level
```
### compare_xyb_constants
Compare XYB conversion constants and full-image conversion accuracy vs C++.
```bash
cargo run --release --example compare_xyb_constants --features "test-utils,ffi-tests"
# Tests specific RGB values and full image conversion
# Shows per-channel max difference
```
### xyb_quality_check ⚠️
Compare XYB quality metrics between Rust and C++.
```bash
cargo run --release --example xyb_quality_check
# NOTE: Currently has a decoder bug with progressive XYB JPEGs
# See tests/progressive_xyb_decode.rs for details
```
## Compatibility Testing
### test_libjpeg_compat
Verify jpegli-rs output is compatible with libjpeg/djpeg decoder.
```bash
cargo run --release --example test_libjpeg_compat
# Tests various image patterns at multiple quality levels
# Verifies djpeg can decode all outputs
```
### generate_cpp_reference
Generate C++ jpegli reference outputs for comparison testing.
```bash
cargo run --release --example generate_cpp_reference
# Requires cjpegli binary in PATH
```
## Dependencies
Some examples require additional features or external tools:
```bash
# For low_q_report and some XYB tools
cargo run --release --example low_q_report --features test-utils
# For C++ comparison tools
cargo run --release --example compare_xyb_constants --features "test-utils,ffi-tests"
```
External tools used by some examples:
- `cjpegli` / `djpegli` - C++ jpegli encoder/decoder (from libjxl)
- Test images in `internal/jpegli-cpp/testdata/`
- Codec corpus at `~/work/codec-eval/codec-corpus/`
## Known Issues
1. **Progressive XYB decode bug**: jpegli-rs decoder fails on progressive XYB JPEGs
generated by C++ cjpegli. See `tests/progressive_xyb_decode.rs` for test case.
- Baseline XYB works fine
- Issue is with non-standard component IDs (R=82, G=71, B=66) in progressive scans
2. **XYB quality gap**: ~5 SSIMULACRA2 gap vs C++ jpegli XYB mode (root cause TBD)
## Adding New Examples
When adding debugging tools:
1. Use `jpegli-bench-utils` crate for synthetic images and metrics
2. Follow naming convention: `<category>_<specific>.rs`
3. Add to this README with usage examples
4. Prefer consolidating into existing tools over creating new files