visual_diff_engine.h

Go to the documentation of this file.

#ifndef YAZE_APP_TEST_VISUAL_DIFF_ENGINE_H_
#define YAZE_APP_TEST_VISUAL_DIFF_ENGINE_H_
 
#include <cstdint>
#include <string>
#include <vector>
 
#include "absl/status/status.h"
#include "absl/status/statusor.h"
#include "app/test/screenshot_assertion.h"
 
namespace yaze {
namespace test {
 
struct VisualDiffResult {
  bool identical = false;       // True if images are pixel-perfect identical
  bool passed = false;          // True if similarity >= tolerance
  float similarity = 0.0f;      // 0.0 to 1.0 (1.0 = identical)
  float difference_pct = 0.0f;  // Percentage of differing pixels
 
  // Image dimensions
  int width = 0;
  int height = 0;
  int total_pixels = 0;
  int differing_pixels = 0;
 
  // Diff visualization
  std::vector<uint8_t> diff_image_png;  // PNG-encoded diff image
  std::string diff_description;         // Human-readable description
 
  // Regions of interest
  struct DiffRegion {
    int x = 0;
    int y = 0;
    int width = 0;
    int height = 0;
    float local_diff_pct = 0.0f;  // Diff percentage in this region
  };
  std::vector<DiffRegion> significant_regions;
 
  // Error info
  std::string error_message;
 
  std::string Format() const;
 
  std::string ToJson() const;
};
 
struct VisualDiffConfig {
  // Similarity threshold (0.0 to 1.0)
  float tolerance = 0.95f;  // 95% similarity = pass
 
  // Per-pixel color tolerance (RGB channels)
  int color_threshold = 10;  // Max RGB difference per channel (0-255)
 
  // Diff image generation
  bool generate_diff_image = true;
  enum class DiffStyle {
    kRedHighlight,    // Red overlay on different pixels
    kSideBySide,      // A | diff | B side by side
    kHeatmap,         // Gradient showing degree of difference
    kBlinkComposite,  // Alternating frames (for animated output)
  };
  DiffStyle diff_style = DiffStyle::kRedHighlight;
 
  // Comparison algorithm
  enum class Algorithm {
    kPixelExact,       // Exact pixel comparison
    kSSIM,             // Structural Similarity Index
    kPerceptualHash,   // pHash for similarity
  };
  Algorithm algorithm = Algorithm::kPixelExact;
 
  // Region detection
  int region_merge_distance = 16;  // Merge nearby diff regions (pixels)
  int min_region_size = 4;         // Minimum region size to report (pixels)
 
  // Ignore regions (for dynamic content)
  std::vector<ScreenRegion> ignore_regions;
};
 
class VisualDiffEngine {
 public:
  VisualDiffEngine();
  explicit VisualDiffEngine(const VisualDiffConfig& config);
  ~VisualDiffEngine() = default;
 
  // Configuration
  void SetConfig(const VisualDiffConfig& config) { config_ = config; }
  const VisualDiffConfig& GetConfig() const { return config_; }
  void SetTolerance(float tolerance) { config_.tolerance = tolerance; }
 
  // --- Core Comparison Methods ---
 
  absl::StatusOr<VisualDiffResult> ComparePngFiles(const std::string& path_a,
                                                   const std::string& path_b);
 
  absl::StatusOr<VisualDiffResult> ComparePngData(
      const std::vector<uint8_t>& png_a, const std::vector<uint8_t>& png_b);
 
  absl::StatusOr<VisualDiffResult> CompareWithReference(
      const std::vector<uint8_t>& png_data, const std::string& reference_path);
 
  VisualDiffResult CompareScreenshots(const Screenshot& a, const Screenshot& b);
 
  // --- Region Comparison ---
 
  absl::StatusOr<VisualDiffResult> CompareRegion(
      const std::vector<uint8_t>& png_a, const std::vector<uint8_t>& png_b,
      const ScreenRegion& region);
 
  // --- Diff Image Generation ---
 
  absl::StatusOr<std::vector<uint8_t>> GenerateDiffPng(const Screenshot& a,
                                                       const Screenshot& b);
 
  absl::Status SaveDiffImage(const VisualDiffResult& result,
                             const std::string& output_path);
 
  // --- Utility Methods ---
 
  static absl::StatusOr<Screenshot> DecodePng(
      const std::vector<uint8_t>& png_data);
 
  static absl::StatusOr<std::vector<uint8_t>> EncodePng(
      const Screenshot& screenshot);
 
  static absl::StatusOr<Screenshot> LoadPng(const std::string& path);
 
  static absl::Status SavePng(const Screenshot& screenshot,
                              const std::string& path);
 
  // --- SSIM Calculation ---
 
  static float CalculateSSIM(const Screenshot& a, const Screenshot& b);
 
  static float CalculateRegionSSIM(const Screenshot& a, const Screenshot& b,
                                   const ScreenRegion& region);
 
 private:
  VisualDiffConfig config_;
 
  // Core comparison implementation
  VisualDiffResult CompareImpl(const Screenshot& a, const Screenshot& b,
                               const ScreenRegion& region);
 
  // Pixel-exact comparison
  VisualDiffResult ComparePixelExact(const Screenshot& a, const Screenshot& b,
                                     const ScreenRegion& region);
 
  // SSIM-based comparison
  VisualDiffResult CompareSSIM(const Screenshot& a, const Screenshot& b,
                               const ScreenRegion& region);
 
  // Diff image generation
  std::vector<uint8_t> GenerateRedHighlightDiff(const Screenshot& a,
                                                const Screenshot& b,
                                                const VisualDiffResult& result);
  std::vector<uint8_t> GenerateHeatmapDiff(const Screenshot& a,
                                           const Screenshot& b);
  std::vector<uint8_t> GenerateSideBySideDiff(const Screenshot& a,
                                              const Screenshot& b,
                                              const VisualDiffResult& result);
 
  // Region detection
  std::vector<VisualDiffResult::DiffRegion> FindSignificantRegions(
      const Screenshot& a, const Screenshot& b, int threshold);
  void MergeNearbyRegions(std::vector<VisualDiffResult::DiffRegion>& regions);
 
  // Helpers
  bool ColorsMatch(const uint8_t* pixel_a, const uint8_t* pixel_b) const;
  float PixelDifference(const uint8_t* pixel_a, const uint8_t* pixel_b) const;
};
 
}  // namespace test
}  // namespace yaze
 
#endif  // YAZE_APP_TEST_VISUAL_DIFF_ENGINE_H_