Package eu.svjatoslav.sixth.e3d.headless

Class GoldenImage

java.lang.Object

eu.svjatoslav.sixth.e3d.headless.GoldenImage

public final class GoldenImage
extends Object

Golden-image comparison: render a scene, compare against a committed reference PNG, fail when the picture drifts.

A pixel counts as different when any RGB channel differs by more than a per-channel tolerance; a comparison fails when the fraction of differing pixels exceeds a threshold. Both are parameters — shading and antialiasing make exact matches fragile, but "the floor lost 30% of its pixels" must not pass.

Example:

 BufferedImage actual = Snapshot.render(scene, lighting, pose, 640, 480);
 GoldenImage.Result r = GoldenImage.compare(actual, new File("goldens/house.png"), 8, 0.01);
 if (!r.passed) {
     GoldenImage.saveDiff(actual, new File("goldens/house.png"), "/tmp/diff.png");
     throw new AssertionError(r.toString());
 }
 

Command line (for scripts):

 java eu.svjatoslav.sixth.e3d.headless.GoldenImage actual.png golden.png [tolerance] [maxDiffFraction]
 exit code 0 = match, 1 = differ, 2 = usage/io error
 

See Also:

• Snapshot

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	GoldenImage.Result	Outcome of one comparison.

Method Summary

Modifier and Type	Method	Description
static GoldenImage.Result	compare(BufferedImage actual, File goldenFile, int channelTolerance, double maxDiffFraction)	Compares an image against a golden PNG file.
static void	main(String[] args)	CLI: compares two PNGs.
static void	saveDiff(BufferedImage actual, File goldenFile, String outPath)	Writes a visual diff image: matching pixels dimmed, differing pixels highlighted red.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

compare

public static GoldenImage.Result compare(BufferedImage actual,
 File goldenFile,
 int channelTolerance,
 double maxDiffFraction)
                                  throws IOException

Compares an image against a golden PNG file.

Parameters:

actual - the rendered image

goldenFile - the reference PNG

channelTolerance - per-channel (R/G/B) tolerance, 0 = exact

maxDiffFraction - maximum allowed fraction of differing pixels (0..1)

Returns:

the comparison result

Throws:

IOException - on read failure or size mismatch

saveDiff

public static void saveDiff(BufferedImage actual,
 File goldenFile,
 String outPath)
                     throws IOException

Writes a visual diff image: matching pixels dimmed, differing pixels highlighted red. Handy for inspecting a failed comparison.

Parameters:

actual - the rendered image

goldenFile - the reference PNG

outPath - where to write the diff PNG

Throws:

IOException - on read/write failure or size mismatch

main

public static void main(String[] args)

CLI: compares two PNGs. Exit 0 = match, 1 = differ, 2 = error.

Parameters:

args - actual.png golden.png [channelTolerance] [maxDiffFraction]