Enhance benchmark CLI with GPU, HTJ2K, and compare-all modes

[Copilot]

Description

Extends the j2k benchmark CLI command with multi-backend benchmarking: CPU, GPU (Metal), and HTJ2K (Part 15 FBCOT). Adds --compare-all for side-by-side comparison tables with speedup ratios. Handles no-GPU gracefully via transparent CPU fallback with explicit reporting.

Also addresses code review feedback on HTJ2K block coder: deduplicates header parsing, removes force unwraps, uses idiomatic Swift for max computation.

Motivation

The existing benchmark command only measured CPU Part 1 encoding/decoding. No way to compare GPU-accelerated or HTJ2K pipelines, and no handling for systems without Metal (Linux, headless CI).

Changes

Benchmark CLI (Sources/J2KCLI/Benchmark.swift)

• Add --gpu, --htj2k, --compare-all benchmark modes via BenchmarkMode enum
• Runtime GPU detection using MTLCreateSystemDefaultDevice() (not just canImport(Metal)) to handle headless Macs
• CPU fallback with ⚠ warning when GPU requested but unavailable
• Comparison summary table with encode/decode times, throughput (MP/s), and speedup ratios
• gpu_available and gpu_backend fields in JSON/CSV output
• Refactored into benchmarkEncode/benchmarkDecode helpers; fixed division-by-zero guard in computeStats

HTJ2K block coder (Sources/J2KCodec/J2KHTBlockCoder.swift)

• Extract HTStreamHeader struct to deduplicate 6-byte header parsing between decodeCleanup and decodeFromCodestream

Encoder pipeline (Sources/J2KCodec/J2KEncoderPipeline.swift)

• Replace absMags.reduce(0) { Swift.max($0, $1) } with absMags.max() ?? 0

Help text (Sources/J2KCLI/main.swift)

• Add --gpu, --htj2k, --compare-all to BENCHMARK OPTIONS

# Side-by-side CPU vs GPU vs HTJ2K comparison
j2k benchmark -i test.pgm --compare-all -r 10

# GPU-only (falls back to CPU on Linux with warning)
j2k benchmark -i test.pgm --gpu --format csv -o results.csv

Testing

• Unit tests added/updated
• Integration tests added/updated
• Manual testing performed
• All tests pass locally

Documentation

• API documentation updated
• README updated (if needed)
• CHANGELOG updated (if needed)

Code Quality

• SwiftLint passes
• No new warnings
• Code follows project style guide
• Breaking changes documented (if any)

Screenshots (if applicable)

N/A

Checklist

• My code follows the project's code style
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published

Related Issues