0023272: Image comparison algorithm
[occt.git] / src / Image / Image_Diff.hxx
CommitLineData
692613e5 1// Created on: 2012-07-10
2// Created by: VRO
3// Copyright (c) 2012 OPEN CASCADE SAS
4//
5// The content of this file is subject to the Open CASCADE Technology Public
6// License Version 6.5 (the "License"). You may not use the content of this file
7// except in compliance with the License. Please obtain a copy of the License
8// at http://www.opencascade.org and read it completely before using this file.
9//
10// The Initial Developer of the Original Code is Open CASCADE S.A.S., having its
11// main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France.
12//
13// The Original Code and all software distributed under the License is
14// distributed on an "AS IS" basis, without warranty of any kind, and the
15// Initial Developer hereby disclaims all such warranties, including without
16// limitation, any warranties of merchantability, fitness for a particular
17// purpose or non-infringement. Please see the License for the specific terms
18// and conditions governing the rights and limitations under the License.
19
20#ifndef _Image_Diff_H__
21#define _Image_Diff_H__
22
23#include <Image_PixMap.hxx>
24#include <TCollection_AsciiString.hxx>
25#include <TColStd_MapOfInteger.hxx>
26#include <NCollection_List.hxx>
27#include <NCollection_Vector.hxx>
28
29//! This class compares two images pixel-by-pixel.
30//! It uses the following methods to ignore the difference between images:
31//! - Black/White comparison. It makes the images 2-colored before the comparison.
32//! - Equality with tolerance. Colors of two pixels are considered the same if the
33//! differnce of their color is less than a tolerance.
34//! - Border filter. The algorithm ignores alone independent pixels,
35//! which are different on both images, ignores the "border effect" -
36//! the difference caused by triangles located at angle about 0 or 90 degrees to the user.
37//!
38//! Border filter ignores a difference in implementation of
39//! anti-aliasing and other effects on boundary of a shape.
40//! The triangles of a boundary zone are usually located so that their normals point aside the user
41//! (about 90 degree between the normal and the direction to the user's eye).
42//! Deflection of the light for such a triangle depends on implementation of the video driver.
43//! In order to skip this difference the following algorithm is used:
44//! a) "Different" pixels are groupped and checked on "one-pixel width line".
45//! indeed, the pixels may represent not a line, but any curve.
46//! But the width of this curve should be not more than a pixel.
47//! This group of pixels become a candidate to be ignored because of boundary effect.
48//! b) The group of pixels is checked on belonging to a "shape".
49//! Neighbour pixels are checked from the reference image.
50//! This test confirms a fact that the group of pixels belongs to a shape and
51//! represent a boundary of the shape.
52//! In this case the whole group of pixels is ignored (considered as same).
53//! Otherwise, the group of pixels may represent a geometrical curve in the viewer 3D
54//! and should be considered as "different".
55class Image_Diff : public Standard_Transient
56{
57
58public:
59
60 //! An empty constructor. Init() should be called for initialization.
61 Standard_EXPORT Image_Diff();
62
63 //! Desctructor.
64 Standard_EXPORT virtual ~Image_Diff();
65
66 //! Initialize algorithm by two images.
67 //! @return false if images has different or unsupported pixel format.
68 Standard_EXPORT Standard_Boolean Init (const Handle(Image_PixMap)& theImageRef,
69 const Handle(Image_PixMap)& theImageNew,
70 const Standard_Boolean theToBlackWhite = Standard_False);
71
72 //! Initialize algorithm by two images (will be loaded from files).
73 //! @return false if images couldn't be opened or their format is unsupported.
74 Standard_EXPORT Standard_Boolean Init (const TCollection_AsciiString& theImgPathRef,
75 const TCollection_AsciiString& theImgPathNew,
76 const Standard_Boolean theToBlackWhite = Standard_False);
77
78 //! Color tolerance for equality check. Should be within range 0..1:
79 //! Corresponds to a difference between white and black colors (maximum difference).
80 //! By default, the tolerance is equal to 0 thus equality check will return false for any different colors.
81 Standard_EXPORT void SetColorTolerance (const Standard_Real theTolerance);
82
83 //! Color tolerance for equality check.
84 Standard_EXPORT Standard_Real ColorTolerance() const;
85
86 //! Sets taking into account (ignoring) a "border effect" on comparison of images.
87 //! The border effect is caused by a border of shaded shapes in the viewer 3d.
88 //! Triangles of this area are located at about 0 or 90 degrees to the user.
89 //! Therefore, they deflect light differently according to implementation of a video card driver.
90 //! This flag allows to detect such a "border" area and skip it from comparison of images.
91 //! Filter turned OFF by default.
92 Standard_EXPORT void SetBorderFilterOn (const Standard_Boolean theToIgnore);
93
94 //! Returns a flag of taking into account (ignoring) a border effect in comparison of images.
95 Standard_EXPORT Standard_Boolean IsBorderFilterOn() const;
96
97 //! Compares two images. It returns a number of different pixels (or groups of pixels).
98 //! It returns -1 if algorithm not initialized before.
99 Standard_EXPORT Standard_Integer Compare();
100
101 //! Saves a difference between two images as white pixels on black backgroud.
102 Standard_EXPORT Standard_Boolean SaveDiffImage (Image_PixMap& theDiffImage) const;
103
104 //! Saves a difference between two images as white pixels on black backgroud.
105 Standard_EXPORT Standard_Boolean SaveDiffImage (const TCollection_AsciiString& theDiffPath) const;
106
107protected:
108
109 //! Perform border filter algorithm.
110 Standard_EXPORT Standard_Integer ignoreBorderEffect();
111
112 //! Release dynamically allocated memory.
113 Standard_EXPORT void releaseGroupsOfDiffPixels();
114
115protected:
116
117 typedef NCollection_List<TColStd_MapOfInteger* > ListOfMapOfInteger;
118
119 Handle(Image_PixMap) myImageRef; //!< reference image to compare (from)
120 Handle(Image_PixMap) myImageNew; //!< new image to compare (to)
121 Standard_Real myColorTolerance; //!< tolerance for equality check (0..1, 0 - any not equal, 1 - opposite colors)
122 Standard_Boolean myIsBorderFilterOn; //!< perform algorithm with border effect filter
123 ListOfMapOfInteger myGroupsOfDiffPixels;
124 NCollection_Vector<Standard_Size> myDiffPixels; //!< different pixels (position packed into integer)
125 TColStd_MapOfInteger myLinearGroups;
126
127public:
128
129 DEFINE_STANDARD_RTTI(Image_Diff) // Type definition
130
131};
132
133DEFINE_STANDARD_HANDLE(Image_Diff, Standard_Transient)
134
135#endif // _Image_Diff_H__