This class is used to compare images and find/highlight differences. More...

#include <VzImgCmp.hpp>

Collaboration diagram for vz::ImgCmp:

Public Types
enum	Flags { kNone = 0x0000, kDiffOriginalSize = 0x0001, kDiffResized = 0x0002, kDiffColour = 0x0004, kDiffGreyscale = 0x0008, kThresholdTriangle = 0x0010, kThresholdOtsu = 0x0020, kAnnotateOverGrey = 0x0040, kAnnotateOverColour = 0x0080, kAnnotateAddRedBorder = 0x0100, kAnnotateAddGreenBorder = 0x0200, kDrawContour = 0x0400, kDrawRectangle = 0x0800 }
	Optional features flags. More...

Public Member Functions
	ImgCmp ()
	Empty constructor. You must call set_master_image() before it can be used. More...

	ImgCmp (cv::Mat mat)
	Constructor. Automatically calls set_master_image() with the given `cv::Mat` image. More...

virtual	~ImgCmp ()
	Destructor. More...

virtual ImgCmp &	reset ()
	Reset the object to a known state. More...

virtual std::string	version () const
	Get the version string. Similar to `"1.0.0-1234"`. More...

virtual ImgCmp &	set_flag (const Flags f, const bool verify=false)
	Set a feature flag. Optionally can be told to call verify_flags(). More...

virtual ImgCmp &	clear_flag (const Flags f, const bool verify=false)
	Set a feature flag. Optionally can be told to call verify_flags(). More...

virtual ImgCmp &	verify_flags ()
	This knows about the groupings of the various flags and will ensure that incompatible flags are not set, and that at least 1 of each feature flag groups has been set. More...

virtual VStr	debug_save ()
	Save all the images as .png files using semi-descriptive names for debug purposes. More...

virtual ImgCmp &	set_master_image (cv::Mat img)
	Set the master image against which all other images will be compared. More...

virtual size_t	compare (cv::Mat img)
	Compare the given image against the previously set master image. More...

virtual cv::Mat	annotate ()
	Annotate the most recently compared image. More...

Public Attributes
vz::Imagination	master_original
	Original master image as set by set_master_image. More...

vz::Imagination	master_resized
	Master image reduced to 25% of the original size. More...

vz::Imagination	candy_original
	The target image which is compared against the original is called `candy`. More...

vz::Imagination	candy_resized
	The target image which is compared against the original, but resized to match master_resized. More...

double	resized_image_scale
	Scale to apply when resizing images. More...

cv::Mat	differences
	The differences between the master image and the most recent image after calling compare(). More...

cv::Mat	differences_threshold
	The differences converted to a binary mask using one of the thresholds. More...

vz::VContours	differences_contours
	The contours (each of which is a vector of points) from differences_threshold. More...

double	min_contour_area
	The minimum area a difference must occupy to be retained. Differences smaller than this will be ignored. Units if measurement is "square pixels". More...

int	dilate_and_erode
	The amount of dilation and erosion applied to differences_threshold. More...

cv::Mat	annotated_candy
	The target image which is compared against the original is called `candy`. More...

cv::Scalar	annotation_colour
	The colour that will be used to annotate the images and highlight the differences. More...

int	annotation_thickness
	The thickness of the lines used to annotate the images and highlight the differences. The default is `2`. More...

Flags	flags
	Optional flags. More...

Protected Member Functions
virtual ImgCmp &	diff_images ()
	This is called by compare() to compute differences. More...

virtual ImgCmp &	get_contours ()
	This is called by compare() to get the differences_contours. More...

Detailed Description

This class is used to compare images and find/highlight differences.

There is a single master image against which other images are compared. The output is a combination of a threshold mask, a sequence of contours (the differences) and/or an annotated image.

cv::Mat img = ...; // do something here to get the master image
vz::ImgCmp image_compare;
image_compare.set_flag(vz::ImgCmp::Flags::kAnnotateOverGrey);
image_compare.set_flag(vz::ImgCmp::Flags::kAnnotateAddRedBorder);
image_compare.set_flag(vz::ImgCmp::Flags::kAnnotateAddGreenBorder);
image_compare.set_flag(vz::ImgCmp::Flags::kDrawContour);
image_compare.set_master_image(img);
cv::Mat test = ...; // do something here to get the test image
image_compare.compare(test);
cv::Mat output = image_compare.annotate();

Usual sequence of events:

Instantiate an object of type vz::ImgCmp using the default constructor. It can safely be instantiated on the stack.
Customize the object by calling vz::ImgCmp::set_flag() or manually settings values such as vz::ImgCmp::min_contour_area.
Set the master image with vz::ImgCmp::set_master_image().
Compare the master image against a new image with vz::ImgCmp::compare().
Copy the structures that are needed, such as differences_contours or differences_threshold.
Optionally ask the library to annotate the image with a call to vz::ImgCmp::annotate().
Then the cycle repeats with a new call to vz::ImgCmp::compare().

Member Enumeration Documentation

◆ Flags

enum vz::ImgCmp::Flags

Optional features flags.

See also: set_flag(); clear_flag(); verify_flags()

Enumerator
kNone
kDiffOriginalSize	Compare the original full-sized image, or the resized copy?
kDiffResized	Compare the original full-sized image, or the resized copy?
kDiffColour	Compare the original colour image, or the greyscale+blurred copy?
kDiffGreyscale	Compare the original colour image, or the greyscale+blurred copy?
kThresholdTriangle	Create the difference threshold using the triangle or Otsu method?
kThresholdOtsu	Create the difference threshold using the triangle or Otsu method?
kAnnotateOverGrey	Determine whether the background image in the annotation is colour or greyscale.
kAnnotateOverColour	Determine whether the background image in the annotation is colour or greyscale.
kAnnotateAddRedBorder	Annotated image will contain a red border if there are differences.
kAnnotateAddGreenBorder	Annotated image will contain a green border if there are no differences.
kDrawContour	The contour of differences will be drawn on the annotated image.
kDrawRectangle	The rotated rectangle which contains the differences will be drawn on the annotated image.

Constructor & Destructor Documentation

◆ ImgCmp() [1/2]

vz::ImgCmp::ImgCmp ( )

Empty constructor. You must call set_master_image() before it can be used.

Here is the call graph for this function:

◆ ImgCmp() [2/2]

vz::ImgCmp::ImgCmp ( cv::Mat mat )

Constructor. Automatically calls set_master_image() with the given cv::Mat image.

Here is the call graph for this function:

◆ ~ImgCmp()

vz::ImgCmp::~ImgCmp ( )

virtual

Destructor.

Member Function Documentation

◆ reset()

vz::ImgCmp & vz::ImgCmp::reset ( )

virtual

Reset the object to a known state.

This is automatically called by the constructors, but is not called by set_master_image().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ version()

std::string vz::ImgCmp::version ( ) const

virtual

Get the version string. Similar to "1.0.0-1234".

◆ set_flag()

vz::ImgCmp & vz::ImgCmp::set_flag	(	const Flags	f,
		const bool	verify = `false`
	)

virtual

Set a feature flag. Optionally can be told to call verify_flags().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ clear_flag()

vz::ImgCmp & vz::ImgCmp::clear_flag	(	const Flags	f,
		const bool	verify = `false`
	)

virtual

Set a feature flag. Optionally can be told to call verify_flags().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ verify_flags()

vz::ImgCmp & vz::ImgCmp::verify_flags ( )

virtual

This knows about the groupings of the various flags and will ensure that incompatible flags are not set, and that at least 1 of each feature flag groups has been set.

This is automatically called by some key API calls, such as compare().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ debug_save()

vz::VStr vz::ImgCmp::debug_save ( )

virtual

Save all the images as .png files using semi-descriptive names for debug purposes.

Returns: A vector of all the saved image filenames.

◆ set_master_image()

vz::ImgCmp & vz::ImgCmp::set_master_image ( cv::Mat img )

virtual

Set the master image against which all other images will be compared.

The image is cloned prior to set_master_image() returning, so the original cv::Mat can be modified, reused, or destroyed without it causing any problems.

Note: This does not call reset(), so previous customizations such as annotation colour and feature flags will be retained even when setting a new master image.

Once you've called set_master_image() (either directly or via the class constructor that takes a cv::Mat) then you may call compare().

Exceptions

std::invalid_argument if the new master image seems to be invalid

Here is the call graph for this function:

Here is the caller graph for this function:

◆ compare()

size_t vz::ImgCmp::compare ( cv::Mat img )

virtual

Compare the given image against the previously set master image.

Returns: The number of differences found in the image. (This is the number of vectors stored in differences_contours.)

Note: This does not automatically call annotate. If you want the annotated version of the image, you must explicitly call annotate().

See also: set_master_image(); differences; differences_threshold; differences_contours

Exceptions

std::logic_error	if the master image has not yet been defined
std::invalid_argument	if the new image seems to be invalid

Here is the call graph for this function:

◆ annotate()

cv::Mat vz::ImgCmp::annotate ( )

virtual

Annotate the most recently compared image.

You must call compare() prior to this method. The annotated image will also be stored in annotated_candy.

Annotation on full-colour image:
Annotation where only the differences are in colour:

See also: annotated_candy

◆ diff_images()

vz::ImgCmp & vz::ImgCmp::diff_images ( )

protectedvirtual

This is called by compare() to compute differences.

Here is the caller graph for this function:

◆ get_contours()

vz::ImgCmp & vz::ImgCmp::get_contours ( )

protectedvirtual

This is called by compare() to get the differences_contours.

Here is the caller graph for this function:

Member Data Documentation

◆ master_original

vz::Imagination vz::ImgCmp::master_original

Original master image as set by set_master_image.

See also: master_resized

◆ master_resized

vz::Imagination vz::ImgCmp::master_resized

Master image reduced to 25% of the original size.

See also: master_original; resized_image_scale

◆ candy_original

vz::Imagination vz::ImgCmp::candy_original

The target image which is compared against the original is called candy.

See also: candy_resized; resized_image_scale

◆ candy_resized

vz::Imagination vz::ImgCmp::candy_resized

The target image which is compared against the original, but resized to match master_resized.

◆ resized_image_scale

double vz::ImgCmp::resized_image_scale

Scale to apply when resizing images.

Default is 0.25, meaning resized image will be 1/4 the size of the original. If you change this value, you must call set_master_image() again to ensure that master_resized has been set correctly.

◆ differences

cv::Mat vz::ImgCmp::differences

The differences between the master image and the most recent image after calling compare().

This image may be colour or greyscale (single channel) depending on whether kDiffColour or kDiffGreyscale has been set.

Starting with the example image,

colour differences
greyscale differences

See also: differences_threshold

◆ differences_threshold

cv::Mat vz::ImgCmp::differences_threshold

The differences converted to a binary mask using one of the thresholds.

There are two threshold methods available, triangle (the default) and Otsu. There may be situations or configurations where Otsu gives better results than the traditional triangle method, though in my testing of the sample images I have on hand the traditional triangle method seems to work better.

Starting with the example image,

triangle threshold
Otsu threshold

See also: kThresholdTriangle; dilate_and_erode

◆ differences_contours

vz::VContours vz::ImgCmp::differences_contours

The contours (each of which is a vector of points) from differences_threshold.

Each contour represents an important difference found when the image was compared against the master in compare().

◆ min_contour_area

double vz::ImgCmp::min_contour_area

The minimum area a difference must occupy to be retained. Differences smaller than this will be ignored. Units if measurement is "square pixels".

◆ dilate_and_erode

int vz::ImgCmp::dilate_and_erode

The amount of dilation and erosion applied to differences_threshold.

Default is 3. Set to zero to disable. Dilation and erosion determine how differences which are near to each other may be combined into a single difference. Without any dilation and erosion, differences are very sharp and stand out easily; each difference is interpreted independently. But differences that are very tiny may be ignored because they fall beneath the threshold of min_contour_area.

There needs to be a balance between having too much, and not enough.

Starting with the example image,

dilate_and_erode=0
dilate_and_erode=5
dilate_and_erode=10

◆ annotated_candy

cv::Mat vz::ImgCmp::annotated_candy

The target image which is compared against the original is called candy.

This is the annotated version, highlighting all of the differences. This image is only generated when annotate() is called.

Starting with the example image,

With kAnnotateOverGrey, this means the background image is greyscale and only the parts that are different are shown in colour:
With kAnnotateOverColour, the entire image is shown in colour:
With kAnnotateAddRedBorder, a red border is added to the image if any differences have been detected:
With kDrawRectangle and without kDrawContour, rotated rectangles are displayed around each difference:
With both kDrawContour and kDrawRectangle, both the contour and rotated rectangles are displayed:

◆ annotation_colour

cv::Scalar vz::ImgCmp::annotation_colour

The colour that will be used to annotate the images and highlight the differences.

The default colour is pure red.

Note: Remember that OpenCV uses BGR, not RGB. For example, red is "{0, 0, 255}" while blue is "{255, 0, 0}".

◆ annotation_thickness

int vz::ImgCmp::annotation_thickness

The thickness of the lines used to annotate the images and highlight the differences. The default is 2.

◆ flags

Flags vz::ImgCmp::flags

Optional flags.

Instead of accessing this member directly, please use set_flag() and clear_flag() which has additional logic to ensure conflicting features aren't set.

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

VzImgCmp.hpp
VzImgCmp.cpp

Public Types

Public Member Functions

Public Attributes

Protected Member Functions

Detailed Description

Member Enumeration Documentation

◆ Flags

Constructor & Destructor Documentation

◆ ImgCmp() [1/2]

◆ ImgCmp() [2/2]

◆ ~ImgCmp()

Member Function Documentation

◆ reset()

◆ version()

◆ set_flag()

◆ clear_flag()

◆ verify_flags()

◆ debug_save()

◆ set_master_image()

◆ compare()

◆ annotate()

◆ diff_images()

◆ get_contours()

Member Data Documentation

◆ master_original

◆ master_resized

◆ candy_original

◆ candy_resized

◆ resized_image_scale

◆ differences

◆ differences_threshold

◆ differences_contours

◆ min_contour_area

◆ dilate_and_erode

◆ annotated_candy

◆ annotation_colour

◆ annotation_thickness

◆ flags