yaze::test::VisualDiffEngine Class Reference

High-level visual comparison engine for gRPC/MCP integration. More...

#include <visual_diff_engine.h>

Collaboration diagram for yaze::test::VisualDiffEngine:

Public Member Functions
	VisualDiffEngine ()
	VisualDiffEngine (const VisualDiffConfig &config)
	~VisualDiffEngine ()=default
void	SetConfig (const VisualDiffConfig &config)
const VisualDiffConfig &	GetConfig () const
void	SetTolerance (float tolerance)
absl::StatusOr< VisualDiffResult >	ComparePngFiles (const std::string &path_a, const std::string &path_b)
	Compare two PNG files.
absl::StatusOr< VisualDiffResult >	ComparePngData (const std::vector< uint8_t > &png_a, const std::vector< uint8_t > &png_b)
	Compare two PNG images from raw data.
absl::StatusOr< VisualDiffResult >	CompareWithReference (const std::vector< uint8_t > &png_data, const std::string &reference_path)
	Compare PNG data against a reference file.
VisualDiffResult	CompareScreenshots (const Screenshot &a, const Screenshot &b)
	Compare two Screenshot objects directly.
absl::StatusOr< VisualDiffResult >	CompareRegion (const std::vector< uint8_t > &png_a, const std::vector< uint8_t > &png_b, const ScreenRegion &region)
	Compare a specific region of two images.
absl::StatusOr< std::vector< uint8_t > >	GenerateDiffPng (const Screenshot &a, const Screenshot &b)
	Generate a diff image highlighting differences.
absl::Status	SaveDiffImage (const VisualDiffResult &result, const std::string &output_path)
	Save diff image to file.

Static Public Member Functions
static absl::StatusOr< Screenshot >	DecodePng (const std::vector< uint8_t > &png_data)
	Decode PNG data to Screenshot.
static absl::StatusOr< std::vector< uint8_t > >	EncodePng (const Screenshot &screenshot)
	Encode Screenshot to PNG.
static absl::StatusOr< Screenshot >	LoadPng (const std::string &path)
	Load PNG from file.
static absl::Status	SavePng (const Screenshot &screenshot, const std::string &path)
	Save screenshot to PNG file.
static float	CalculateSSIM (const Screenshot &a, const Screenshot &b)
	Calculate Structural Similarity Index.
static float	CalculateRegionSSIM (const Screenshot &a, const Screenshot &b, const ScreenRegion &region)
	Calculate SSIM for a specific region.

Private Member Functions
VisualDiffResult	CompareImpl (const Screenshot &a, const Screenshot &b, const ScreenRegion &region)
VisualDiffResult	ComparePixelExact (const Screenshot &a, const Screenshot &b, const ScreenRegion &region)
VisualDiffResult	CompareSSIM (const Screenshot &a, const Screenshot &b, const ScreenRegion &region)
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)
std::vector< VisualDiffResult::DiffRegion >	FindSignificantRegions (const Screenshot &a, const Screenshot &b, int threshold)
void	MergeNearbyRegions (std::vector< VisualDiffResult::DiffRegion > &regions)
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

Private Attributes
VisualDiffConfig	config_

Detailed Description

High-level visual comparison engine for gRPC/MCP integration.

Provides PNG-to-PNG comparison with structured results suitable for:

• gRPC VisualService
• MCP visual_compare tool
• Visual regression testing
• AI-assisted debugging workflows

Usage:

VisualDiffEngine engine;
 
// Compare two PNG files
auto result = engine.ComparePngFiles("before.png", "after.png");
if (result.ok() && result->passed) {
  LOG(INFO) << "Images match with " << result->similarity * 100 << "% similarity";
}
 
// Compare raw PNG data
auto result = engine.ComparePngData(png_a, png_b);
 
// Compare with reference (regression test)
auto result = engine.CompareWithReference(current_png, "reference/expected.png");

Definition at line 123 of file visual_diff_engine.h.

Constructor & Destructor Documentation

VisualDiffEngine() [1/2]

yaze::test::VisualDiffEngine::VisualDiffEngine ( )

default

VisualDiffEngine() [2/2]

yaze::test::VisualDiffEngine::VisualDiffEngine ( const VisualDiffConfig & config )

explicit

Definition at line 136 of file visual_diff_engine.cc.

~VisualDiffEngine()

yaze::test::VisualDiffEngine::~VisualDiffEngine ( )

default

Member Function Documentation

SetConfig()

void yaze::test::VisualDiffEngine::SetConfig ( const VisualDiffConfig & config )

inline

Definition at line 130 of file visual_diff_engine.h.

References config_.

GetConfig()

const VisualDiffConfig & yaze::test::VisualDiffEngine::GetConfig ( ) const

inline

Definition at line 131 of file visual_diff_engine.h.

References config_.

SetTolerance()

void yaze::test::VisualDiffEngine::SetTolerance ( float tolerance )

inline

Definition at line 132 of file visual_diff_engine.h.

References config_, and yaze::test::VisualDiffConfig::tolerance.

ComparePngFiles()

absl::StatusOr< VisualDiffResult > yaze::test::VisualDiffEngine::ComparePngFiles	(	const std::string &	path_a,
		const std::string &	path_b )

Compare two PNG files.

Parameters

path_a	Path to first PNG image
path_b	Path to second PNG image

Returns

VisualDiffResult with comparison results

Definition at line 139 of file visual_diff_engine.cc.

References CompareScreenshots(), and LoadPng().

Here is the call graph for this function:

ComparePngData()

absl::StatusOr< VisualDiffResult > yaze::test::VisualDiffEngine::ComparePngData	(	const std::vector< uint8_t > &	png_a,
		const std::vector< uint8_t > &	png_b )

Compare two PNG images from raw data.

Parameters

png_a	First PNG image data (raw bytes)
png_b	Second PNG image data (raw bytes)

Returns

VisualDiffResult with comparison results

Definition at line 154 of file visual_diff_engine.cc.

References CompareScreenshots(), and DecodePng().

Here is the call graph for this function:

CompareWithReference()

absl::StatusOr< VisualDiffResult > yaze::test::VisualDiffEngine::CompareWithReference	(	const std::vector< uint8_t > &	png_data,
		const std::string &	reference_path )

Compare PNG data against a reference file.

Parameters

png_data	Current PNG image data
reference_path	Path to reference PNG file

Returns

VisualDiffResult with comparison results

Definition at line 169 of file visual_diff_engine.cc.

References CompareScreenshots(), DecodePng(), and LoadPng().

Here is the call graph for this function:

CompareScreenshots()

VisualDiffResult yaze::test::VisualDiffEngine::CompareScreenshots	(	const Screenshot &	a,
		const Screenshot &	b )

Compare two Screenshot objects directly.

Parameters

a	First screenshot
b	Second screenshot

Returns

VisualDiffResult with comparison results

Definition at line 184 of file visual_diff_engine.cc.

References CompareImpl(), and yaze::test::ScreenRegion::FullScreen().

Referenced by ComparePngData(), ComparePngFiles(), CompareWithReference(), and GenerateDiffPng().

Here is the call graph for this function:

CompareRegion()

absl::StatusOr< VisualDiffResult > yaze::test::VisualDiffEngine::CompareRegion	(	const std::vector< uint8_t > &	png_a,
		const std::vector< uint8_t > &	png_b,
		const ScreenRegion &	region )

Compare a specific region of two images.

Parameters

png_a	First PNG image data
png_b	Second PNG image data
region	Region to compare

Returns

VisualDiffResult for the specified region

Definition at line 189 of file visual_diff_engine.cc.

References CompareImpl(), and DecodePng().

Here is the call graph for this function:

GenerateDiffPng()

absl::StatusOr< std::vector< uint8_t > > yaze::test::VisualDiffEngine::GenerateDiffPng	(	const Screenshot &	a,
		const Screenshot &	b )

Generate a diff image highlighting differences.

Parameters

a	First screenshot
b	Second screenshot

Returns

PNG-encoded diff image

Definition at line 636 of file visual_diff_engine.cc.

References CompareScreenshots(), yaze::test::VisualDiffResult::diff_image_png, and GenerateRedHighlightDiff().

Here is the call graph for this function:

SaveDiffImage()

absl::Status yaze::test::VisualDiffEngine::SaveDiffImage	(	const VisualDiffResult &	result,
		const std::string &	output_path )

Save diff image to file.

Parameters

result	Comparison result containing diff image
output_path	Path to save the diff PNG

Returns

Status indicating success or failure

Definition at line 645 of file visual_diff_engine.cc.

References yaze::test::VisualDiffResult::diff_image_png.

DecodePng()

absl::StatusOr< Screenshot > yaze::test::VisualDiffEngine::DecodePng ( const std::vector< uint8_t > & png_data )

static

Decode PNG data to Screenshot.

Parameters

png_data

Raw PNG bytes

Returns

Screenshot with decoded RGBA data

Definition at line 663 of file visual_diff_engine.cc.

References yaze::test::Screenshot::data, yaze::test::Screenshot::height, and yaze::test::Screenshot::width.

Referenced by ComparePngData(), CompareRegion(), CompareWithReference(), and LoadPng().

EncodePng()

absl::StatusOr< std::vector< uint8_t > > yaze::test::VisualDiffEngine::EncodePng ( const Screenshot & screenshot )

static

Encode Screenshot to PNG.

Parameters

screenshot

Screenshot to encode

Returns

PNG-encoded bytes

Definition at line 735 of file visual_diff_engine.cc.

References yaze::test::Screenshot::data, yaze::test::Screenshot::height, yaze::test::Screenshot::IsValid(), and yaze::test::Screenshot::width.

Referenced by GenerateHeatmapDiff(), GenerateRedHighlightDiff(), GenerateSideBySideDiff(), and SavePng().

Here is the call graph for this function:

LoadPng()

absl::StatusOr< Screenshot > yaze::test::VisualDiffEngine::LoadPng ( const std::string & path )

static

Load PNG from file.

Parameters

path	Path to PNG file

Returns

Screenshot with loaded data

Definition at line 782 of file visual_diff_engine.cc.

References DecodePng().

Referenced by ComparePngFiles(), and CompareWithReference().

Here is the call graph for this function:

SavePng()

absl::Status yaze::test::VisualDiffEngine::SavePng ( const Screenshot & screenshot, const std::string & path )

static

Save screenshot to PNG file.

Parameters

screenshot	Screenshot to save
path	Output path

Returns

Status indicating success or failure

Definition at line 802 of file visual_diff_engine.cc.

References EncodePng().

Here is the call graph for this function:

CalculateSSIM()

float yaze::test::VisualDiffEngine::CalculateSSIM ( const Screenshot & a, const Screenshot & b )

static

Calculate Structural Similarity Index.

Parameters

a	First screenshot
b	Second screenshot

Returns

SSIM value (0.0 to 1.0)

Definition at line 351 of file visual_diff_engine.cc.

References CalculateRegionSSIM(), and yaze::test::ScreenRegion::FullScreen().

Referenced by CompareSSIM().

Here is the call graph for this function:

CalculateRegionSSIM()

float yaze::test::VisualDiffEngine::CalculateRegionSSIM ( const Screenshot & a, const Screenshot & b, const ScreenRegion & region )

static

Calculate SSIM for a specific region.

Parameters

a	First screenshot
b	Second screenshot
region	Region to analyze

Returns

SSIM value for the region

Definition at line 355 of file visual_diff_engine.cc.

References yaze::test::Screenshot::data, yaze::test::Screenshot::GetPixelIndex(), yaze::test::ScreenRegion::height, yaze::test::Screenshot::height, yaze::test::ScreenRegion::IsFullScreen(), yaze::test::ScreenRegion::width, yaze::test::Screenshot::width, yaze::test::ScreenRegion::x, and yaze::test::ScreenRegion::y.

Referenced by CalculateSSIM(), and CompareSSIM().

Here is the call graph for this function:

CompareImpl()

VisualDiffResult yaze::test::VisualDiffEngine::CompareImpl ( const Screenshot & a, const Screenshot & b, const ScreenRegion & region )

private

Definition at line 205 of file visual_diff_engine.cc.

References yaze::test::VisualDiffConfig::algorithm, yaze::test::VisualDiffConfig::color_threshold, ComparePixelExact(), CompareSSIM(), config_, yaze::test::VisualDiffResult::diff_description, yaze::test::VisualDiffResult::diff_image_png, yaze::test::VisualDiffConfig::diff_style, yaze::test::VisualDiffResult::error_message, FindSignificantRegions(), yaze::test::VisualDiffConfig::generate_diff_image, GenerateHeatmapDiff(), GenerateRedHighlightDiff(), GenerateSideBySideDiff(), yaze::test::Screenshot::height, yaze::test::VisualDiffResult::height, yaze::test::VisualDiffResult::identical, yaze::test::Screenshot::IsValid(), yaze::test::VisualDiffConfig::kHeatmap, yaze::test::VisualDiffConfig::kPerceptualHash, yaze::test::VisualDiffConfig::kPixelExact, yaze::test::VisualDiffConfig::kRedHighlight, yaze::test::VisualDiffConfig::kSideBySide, yaze::test::VisualDiffConfig::kSSIM, MergeNearbyRegions(), yaze::test::VisualDiffResult::passed, yaze::test::VisualDiffResult::significant_regions, yaze::test::VisualDiffResult::similarity, yaze::test::VisualDiffConfig::tolerance, yaze::test::Screenshot::width, and yaze::test::VisualDiffResult::width.

Referenced by CompareRegion(), and CompareScreenshots().

ComparePixelExact()

VisualDiffResult yaze::test::VisualDiffEngine::ComparePixelExact ( const Screenshot & a, const Screenshot & b, const ScreenRegion & region )

private

Definition at line 287 of file visual_diff_engine.cc.

References ColorsMatch(), config_, yaze::test::Screenshot::data, yaze::test::VisualDiffResult::difference_pct, yaze::test::VisualDiffResult::differing_pixels, yaze::test::Screenshot::GetPixelIndex(), yaze::test::ScreenRegion::height, yaze::test::Screenshot::height, yaze::test::VisualDiffResult::height, yaze::test::VisualDiffResult::identical, yaze::test::VisualDiffConfig::ignore_regions, yaze::test::ScreenRegion::IsFullScreen(), yaze::test::VisualDiffResult::similarity, yaze::test::VisualDiffResult::total_pixels, yaze::test::ScreenRegion::width, yaze::test::Screenshot::width, yaze::test::VisualDiffResult::width, yaze::test::ScreenRegion::x, and yaze::test::ScreenRegion::y.

Referenced by CompareImpl(), and CompareSSIM().

Here is the call graph for this function:

CompareSSIM()

VisualDiffResult yaze::test::VisualDiffEngine::CompareSSIM ( const Screenshot & a, const Screenshot & b, const ScreenRegion & region )

private

Definition at line 336 of file visual_diff_engine.cc.

References CalculateRegionSSIM(), CalculateSSIM(), ComparePixelExact(), yaze::test::ScreenRegion::IsFullScreen(), and yaze::test::VisualDiffResult::similarity.

Referenced by CompareImpl().

Here is the call graph for this function:

GenerateRedHighlightDiff()

std::vector< uint8_t > yaze::test::VisualDiffEngine::GenerateRedHighlightDiff ( const Screenshot & a, const Screenshot & b, const VisualDiffResult & result )

private

Definition at line 424 of file visual_diff_engine.cc.

References ColorsMatch(), yaze::test::Screenshot::data, EncodePng(), yaze::test::Screenshot::GetPixelIndex(), yaze::test::Screenshot::height, and yaze::test::Screenshot::width.

Referenced by CompareImpl(), and GenerateDiffPng().

Here is the call graph for this function:

GenerateHeatmapDiff()

std::vector< uint8_t > yaze::test::VisualDiffEngine::GenerateHeatmapDiff ( const Screenshot & a, const Screenshot & b )

private

Definition at line 458 of file visual_diff_engine.cc.

References yaze::test::Screenshot::data, EncodePng(), yaze::test::Screenshot::GetPixelIndex(), yaze::test::Screenshot::height, PixelDifference(), and yaze::test::Screenshot::width.

Referenced by CompareImpl().

Here is the call graph for this function:

GenerateSideBySideDiff()

std::vector< uint8_t > yaze::test::VisualDiffEngine::GenerateSideBySideDiff ( const Screenshot & a, const Screenshot & b, const VisualDiffResult & result )

private

Definition at line 500 of file visual_diff_engine.cc.

References ColorsMatch(), yaze::test::Screenshot::data, EncodePng(), yaze::test::Screenshot::GetPixelIndex(), yaze::test::Screenshot::height, and yaze::test::Screenshot::width.

Referenced by CompareImpl().

Here is the call graph for this function:

FindSignificantRegions()

std::vector< VisualDiffResult::DiffRegion > yaze::test::VisualDiffEngine::FindSignificantRegions ( const Screenshot & a, const Screenshot & b, int threshold )

private

Definition at line 547 of file visual_diff_engine.cc.

References ColorsMatch(), yaze::test::Screenshot::data, yaze::test::Screenshot::GetPixelIndex(), yaze::test::Screenshot::height, yaze::test::VisualDiffResult::DiffRegion::height, yaze::test::VisualDiffResult::DiffRegion::local_diff_pct, yaze::test::Screenshot::width, yaze::test::VisualDiffResult::DiffRegion::width, yaze::test::VisualDiffResult::DiffRegion::x, and yaze::test::VisualDiffResult::DiffRegion::y.

Referenced by CompareImpl().

Here is the call graph for this function:

MergeNearbyRegions()

void yaze::test::VisualDiffEngine::MergeNearbyRegions ( std::vector< VisualDiffResult::DiffRegion > & regions )

private

Definition at line 594 of file visual_diff_engine.cc.

References config_, and yaze::test::VisualDiffConfig::region_merge_distance.

Referenced by CompareImpl().

ColorsMatch()

bool yaze::test::VisualDiffEngine::ColorsMatch ( const uint8_t * pixel_a, const uint8_t * pixel_b ) const

private

Definition at line 408 of file visual_diff_engine.cc.

References yaze::test::VisualDiffConfig::color_threshold, and config_.

Referenced by ComparePixelExact(), FindSignificantRegions(), GenerateRedHighlightDiff(), and GenerateSideBySideDiff().

PixelDifference()

float yaze::test::VisualDiffEngine::PixelDifference ( const uint8_t * pixel_a, const uint8_t * pixel_b ) const

private

Definition at line 416 of file visual_diff_engine.cc.

Referenced by GenerateHeatmapDiff().

Member Data Documentation

config_

VisualDiffConfig yaze::test::VisualDiffEngine::config_

private

Definition at line 272 of file visual_diff_engine.h.

Referenced by ColorsMatch(), CompareImpl(), ComparePixelExact(), GetConfig(), MergeNearbyRegions(), SetConfig(), and SetTolerance().

---

The documentation for this class was generated from the following files:

• src/app/test/visual_diff_engine.h
• src/app/test/visual_diff_engine.cc