Leptonica  1.82.0
Image processing and image analysis suite
compare.c File Reference
#include <string.h>
#include <math.h>
#include "allheaders.h"

Go to the source code of this file.

Functions

static l_ok findHistoGridDimensions (l_int32 n, l_int32 w, l_int32 h, l_int32 *pnx, l_int32 *pny, l_int32 debug)
 
static l_ok pixCompareTilesByHisto (PIX *pix1, PIX *pix2, l_int32 maxgray, l_int32 factor, l_int32 n, l_float32 *pscore, PIXA *pixadebug)
 
l_ok pixEqual (PIX *pix1, PIX *pix2, l_int32 *psame)
 
l_ok pixEqualWithAlpha (PIX *pix1, PIX *pix2, l_int32 use_alpha, l_int32 *psame)
 
l_ok pixEqualWithCmap (PIX *pix1, PIX *pix2, l_int32 *psame)
 
l_ok cmapEqual (PIXCMAP *cmap1, PIXCMAP *cmap2, l_int32 ncomps, l_int32 *psame)
 
l_ok pixUsesCmapColor (PIX *pixs, l_int32 *pcolor)
 
l_ok pixCorrelationBinary (PIX *pix1, PIX *pix2, l_float32 *pval)
 
PIXpixDisplayDiffBinary (PIX *pix1, PIX *pix2)
 
l_ok pixCompareBinary (PIX *pix1, PIX *pix2, l_int32 comptype, l_float32 *pfract, PIX **ppixdiff)
 
l_ok pixCompareGrayOrRGB (PIX *pix1, PIX *pix2, l_int32 comptype, l_int32 plottype, l_int32 *psame, l_float32 *pdiff, l_float32 *prmsdiff, PIX **ppixdiff)
 
l_ok pixCompareGray (PIX *pix1, PIX *pix2, l_int32 comptype, l_int32 plottype, l_int32 *psame, l_float32 *pdiff, l_float32 *prmsdiff, PIX **ppixdiff)
 
l_ok pixCompareRGB (PIX *pix1, PIX *pix2, l_int32 comptype, l_int32 plottype, l_int32 *psame, l_float32 *pdiff, l_float32 *prmsdiff, PIX **ppixdiff)
 
l_ok pixCompareTiled (PIX *pix1, PIX *pix2, l_int32 sx, l_int32 sy, l_int32 type, PIX **ppixdiff)
 
NUMApixCompareRankDifference (PIX *pix1, PIX *pix2, l_int32 factor)
 
l_ok pixTestForSimilarity (PIX *pix1, PIX *pix2, l_int32 factor, l_int32 mindiff, l_float32 maxfract, l_float32 maxave, l_int32 *psimilar, l_int32 details)
 
l_ok pixGetDifferenceStats (PIX *pix1, PIX *pix2, l_int32 factor, l_int32 mindiff, l_float32 *pfractdiff, l_float32 *pavediff, l_int32 details)
 
NUMApixGetDifferenceHistogram (PIX *pix1, PIX *pix2, l_int32 factor)
 
l_ok pixGetPerceptualDiff (PIX *pixs1, PIX *pixs2, l_int32 sampling, l_int32 dilation, l_int32 mindiff, l_float32 *pfract, PIX **ppixdiff1, PIX **ppixdiff2)
 
l_ok pixGetPSNR (PIX *pix1, PIX *pix2, l_int32 factor, l_float32 *ppsnr)
 
l_ok pixaComparePhotoRegionsByHisto (PIXA *pixa, l_float32 minratio, l_float32 textthresh, l_int32 factor, l_int32 n, l_float32 simthresh, NUMA **pnai, l_float32 **pscores, PIX **ppixd, l_int32 debug)
 
l_ok pixComparePhotoRegionsByHisto (PIX *pix1, PIX *pix2, BOX *box1, BOX *box2, l_float32 minratio, l_int32 factor, l_int32 n, l_float32 *pscore, l_int32 debugflag)
 
l_ok pixGenPhotoHistos (PIX *pixs, BOX *box, l_int32 factor, l_float32 thresh, l_int32 n, NUMAA **pnaa, l_int32 *pw, l_int32 *ph, l_int32 debugindex)
 
PIXpixPadToCenterCentroid (PIX *pixs, l_int32 factor)
 
l_ok pixCentroid8 (PIX *pixs, l_int32 factor, l_float32 *pcx, l_float32 *pcy)
 
l_ok pixDecideIfPhotoImage (PIX *pix, l_int32 factor, l_float32 thresh, l_int32 n, NUMAA **pnaa, PIXA *pixadebug)
 
l_ok compareTilesByHisto (NUMAA *naa1, NUMAA *naa2, l_float32 minratio, l_int32 w1, l_int32 h1, l_int32 w2, l_int32 h2, l_float32 *pscore, PIXA *pixadebug)
 
l_ok pixCompareGrayByHisto (PIX *pix1, PIX *pix2, BOX *box1, BOX *box2, l_float32 minratio, l_int32 maxgray, l_int32 factor, l_int32 n, l_float32 *pscore, l_int32 debugflag)
 
l_ok pixCropAlignedToCentroid (PIX *pix1, PIX *pix2, l_int32 factor, BOX **pbox1, BOX **pbox2)
 
l_uint8 * l_compressGrayHistograms (NUMAA *naa, l_int32 w, l_int32 h, size_t *psize)
 
NUMAAl_uncompressGrayHistograms (l_uint8 *bytea, size_t size, l_int32 *pw, l_int32 *ph)
 
l_ok pixCompareWithTranslation (PIX *pix1, PIX *pix2, l_int32 thresh, l_int32 *pdelx, l_int32 *pdely, l_float32 *pscore, l_int32 debugflag)
 
l_ok pixBestCorrelation (PIX *pix1, PIX *pix2, l_int32 area1, l_int32 area2, l_int32 etransx, l_int32 etransy, l_int32 maxshift, l_int32 *tab8, l_int32 *pdelx, l_int32 *pdely, l_float32 *pscore, l_int32 debugflag)
 

Variables

static const l_float32 TINY = 0.00001
 

Detailed Description


     Test for pix equality
          l_int32     pixEqual()
          l_int32     pixEqualWithAlpha()
          l_int32     pixEqualWithCmap()
          l_int32     cmapEqual()
          l_int32     pixUsesCmapColor()

     Binary correlation
          l_int32     pixCorrelationBinary()

     Difference of two images of same size
          l_int32     pixDisplayDiffBinary()
          l_int32     pixCompareBinary()
          l_int32     pixCompareGrayOrRGB()
          l_int32     pixCompareGray()
          l_int32     pixCompareRGB()
          l_int32     pixCompareTiled()

     Other measures of the difference of two images of the same size
          NUMA       *pixCompareRankDifference()
          l_int32     pixTestForSimilarity()
          l_int32     pixGetDifferenceStats()
          NUMA       *pixGetDifferenceHistogram()
          l_int32     pixGetPerceptualDiff()
          l_int32     pixGetPSNR()

     Comparison of photo regions by histogram
          l_int32     pixaComparePhotoRegionsByHisto()  -- top-level
          l_int32     pixComparePhotoRegionsByHisto()  -- top-level for 2
          l_int32     pixGenPhotoHistos()
          PIX        *pixPadToCenterCentroid()
          l_int32     pixCentroid8()
          l_int32     pixDecideIfPhotoImage()
      static l_int32  findHistoGridDimensions()
          l_int32     compareTilesByHisto()

          l_int32     pixCompareGrayByHisto()  -- top-level for 2
      static l_int32  pixCompareTilesByHisto()
          l_int32     pixCropAlignedToCentroid()

          l_uint8    *l_compressGrayHistograms()
          NUMAA      *l_uncompressGrayHistograms()

     Translated images at the same resolution
          l_int32     pixCompareWithTranslation()
          l_int32     pixBestCorrelation()

 For comparing images using tiled histograms, essentially all the
 computation goes into deciding if a region of an image is a photo,
 whether that photo region is amenable to similarity measurements
 using histograms, and finally the calculation of the gray histograms
 for each of the tiled regions.  The actual comparison is essentially
 instantaneous.  Therefore, with a large number of images to compare
 with each other, it is important to first calculate the histograms
 for each image.  Then the comparisons, which go as the square of the
 number of images, actually takes no time.

 A high level function that takes a pixa of images and does
 all comparisons, pixaComparePhotosByHisto(), uses this split
 approach.  It pads the images so that the centroid is in the center,
 which will allow the tiles to be better aligned.

 For testing purposes, two functions are given that do all the work
 to compare just two photo regions:
   *  pixComparePhotoRegionsByHisto() uses the split approach, qualifying
      the images first with pixGenPhotoHistos(), and then comparing
      with compareTilesByHisto().
   *  pixCompareGrayByHisto() aligns the two images by centroid
      and calls pixCompareTilesByHisto() to generate the histograms
      and do the comparison.

Definition in file compare.c.

Function Documentation

◆ cmapEqual()

l_ok cmapEqual ( PIXCMAP cmap1,
PIXCMAP cmap2,
l_int32  ncomps,
l_int32 *  psame 
)

cmapEqual()

Parameters
[in]cmap1
[in]cmap2
[in]ncomps3 for RGB, 4 for RGBA
[out]psame
Returns
0 if OK, 1 on error
Notes:
     (1) This returns same = TRUE if the colormaps have identical entries.
     (2) If ncomps == 4, the alpha components of the colormaps are also
         compared.

Definition at line 480 of file compare.c.

References pixcmapGetCount(), and pixcmapGetRGBA().

◆ compareTilesByHisto()

l_ok compareTilesByHisto ( NUMAA naa1,
NUMAA naa2,
l_float32  minratio,
l_int32  w1,
l_int32  h1,
l_int32  w2,
l_int32  h2,
l_float32 *  pscore,
PIXA pixadebug 
)

compareTilesByHisto()

Parameters
[in]naa1,naa2each is a set of 256 entry histograms
[in]minratiorequiring image sizes be compatible; < 1.0
[in]w1,h1,w2,h2image sizes from which histograms were made
[out]pscoresimilarity score of histograms
[in]pixadebug[optional] use only for debug output
Returns
0 if OK, 1 on error
Notes:
     (1) naa1 and naa2 must be generated using pixGenPhotoHistos(),
         using the same tile sizes.
     (2) The image dimensions must be similar.  The score is 0.0
         if the ratio of widths and heights (smallest / largest)
         exceeds a threshold minratio, which must be between
         0.5 and 1.0.  If set at 1.0, both images must be exactly
         the same size.  A typical value for minratio is 0.9.
     (3) The input pixadebug is null unless debug output is requested.

Definition at line 2730 of file compare.c.

References bmfCreate(), gplotSimple2(), L_CLONE, lept_mkdir(), lept_rmdir(), numaAddNumber(), numaaGetCount(), numaaGetNuma(), numaCreate(), numaEarthMoverDistance(), and numaSetValue().

Referenced by pixaComparePhotoRegionsByHisto(), and pixComparePhotoRegionsByHisto().

◆ findHistoGridDimensions()

static l_ok findHistoGridDimensions ( l_int32  n,
l_int32  w,
l_int32  h,
l_int32 *  pnx,
l_int32 *  pny,
l_int32  debug 
)
static

findHistoGridDimensions()

Parameters
[in]nmax number of grid elements is n^2; typ. n = 3
[in]wwidth of image to be subdivided
[in]hheight of image to be subdivided
[out]pnxnumber of grid elements in x direction
[out]pnynumber of grid elements in y direction
[in]debug1 for debug output to stderr
Returns
0 if OK, 1 on error
Notes:
     (1) This determines the number of subdivisions to be used on
         the image in each direction.  A histogram will be built
         for each subimage.
     (2) The parameter n specifies the "side" of the n x n grid
         of subimages.  If the subimages have an aspect ratio larger
         than 2, the grid will change, using n^2 as a maximum for
         the number of subimages.  For example, if n == 3, but the
         image is 600 x 200 pixels, a 3x3 grid would have subimages
         of 200 x 67 pixels, which is more than 2:1, so we change
         to a 4x2 grid where each subimage has 150 x 100 pixels.

Definition at line 2667 of file compare.c.

References lept_stderr().

Referenced by pixCompareTilesByHisto().

◆ l_compressGrayHistograms()

l_uint8* l_compressGrayHistograms ( NUMAA naa,
l_int32  w,
l_int32  h,
size_t *  psize 
)

l_compressGrayHistograms()

Parameters
[in]naaset of 256-entry histograms
[in]w,hsize of image
[out]psizesize of byte array
Returns
0 if OK, 1 on error
Notes:
     (1) This first writes w and h to the byte array as 4 byte ints.
     (2) Then it normalizes each histogram to a max value of 255,
         and saves each value as a byte.  If there are
         N histograms, the output bytearray has 8 + 256 * N bytes.
     (3) Further compression of the array with zlib yields only about
         a 25% decrease in size, so we don't bother.  If size reduction
         were important, a lossy transform using a 1-dimensional DCT
         would be effective, because we don't care about the fine
         details of these histograms.

Definition at line 3240 of file compare.c.

References L_COPY, l_setDataFourBytes(), numaaGetCount(), numaaGetNuma(), numaaGetNumaCount(), numaDestroy(), numaGetIValue(), numaGetMax(), and numaTransform().

◆ l_uncompressGrayHistograms()

NUMAA* l_uncompressGrayHistograms ( l_uint8 *  bytea,
size_t  size,
l_int32 *  pw,
l_int32 *  ph 
)

l_uncompressGrayHistograms()

Parameters
[in]byteabyte array of size 8 + 256 * N, N an integer
[in]sizesize of byte array
[out]pwwidth of the image that generated the histograms
[out]phheight of the image
Returns
numaa representing N histograms, each with 256 bins, or NULL on error.
Notes:
     (1) The first 8 bytes are read as two 32-bit ints.
     (2) Then this constructs a numaa representing some number of
         gray histograms that are normalized such that the max value
         in each histogram is 255.  The data is stored as a byte
         array, with 256 bytes holding the data for each histogram.
         Each gray histogram was computed from a tile of a grayscale image.

Definition at line 3308 of file compare.c.

References l_getDataFourBytes(), L_INSERT, numaaAddNuma(), numaaCreate(), numaAddNumber(), and numaCreate().

◆ pixaComparePhotoRegionsByHisto()

l_ok pixaComparePhotoRegionsByHisto ( PIXA pixa,
l_float32  minratio,
l_float32  textthresh,
l_int32  factor,
l_int32  n,
l_float32  simthresh,
NUMA **  pnai,
l_float32 **  pscores,
PIX **  ppixd,
l_int32  debug 
)

pixaComparePhotoRegionsByHisto()

Parameters
[in]pixaany depth; colormap OK
[in]minratiorequiring sizes be compatible; < 1.0
[in]textthreshthreshold for text/photo; use 0 for default
[in]factorsubsampling; >= 1
[in]nin range {1, ... 7}. n^2 is the maximum number of subregions for histograms; typ. n = 3.
[in]simthreshthreshold for similarity; use 0 for default
[out]pnaiarray giving similarity class indices
[out]pscores[optional] score matrix as 1-D array of size N^2
[out]ppixd[optional] pix of similarity classes
[in]debug1 to output histograms; 0 otherwise
Returns
0 if OK, 1 on error
Notes:
     (1) This function takes a pixa of cropped photo images and
         compares each one to the others for similarity.
         Each image is first tested to see if it is a photo that can
         be compared by tiled histograms.  If so, it is padded to put
         the centroid in the center of the image, and the histograms
         are generated.  The final step of comparing each histogram
         with all the others is very fast.
     (2) To make the histograms, each image is subdivided in a maximum
         of n^2 subimages.  The parameter n specifies the "side" of
         an n x n grid of such subimages.  If the subimages have an
         aspect ratio larger than 2, the grid will change, again using n^2
         as a maximum for the number of subimages.  For example,
         if n == 3, but the image is 600 x 200 pixels, a 3x3 grid
         would have subimages of 200 x 67 pixels, which is more
         than 2:1, so we change to a 4x2 grid where each subimage
         has 150 x 100 pixels.
     (3) An initial filter gives score = 0 if the ratio of widths
         and heights (smallest / largest) does not exceed a
         threshold minratio.  If set at 1.0, both images must be
         exactly the same size.  A typical value for minratio is 0.9.
     (4) The comparison score between two images is a value in [0.0 .. 1.0].
         If the comparison score >= simthresh, the images are placed in
         the same similarity class.  Default value for simthresh is 0.25.
     (5) An array nai of similarity class indices for pix in the
         input pixa is returned.
     (6) There are two debugging options:
         * An optional 2D matrix of scores is returned as a 1D array.
           A visualization of this is written to a temp file.
         * An optional pix showing the similarity classes can be
           returned.  Text in each input pix is reproduced.
     (7) See the notes in pixComparePhotoRegionsByHisto() for details
         on the implementation.

Definition at line 1930 of file compare.c.

References compareTilesByHisto(), L_CLONE, lept_stderr(), numaAddNumber(), numaCreate(), numaGetIValue(), numaMakeConstant(), numaSetValue(), pixaGetCount(), pixaGetPix(), pixCreate(), pixDestroy(), pixGenPhotoHistos(), pixGetData(), pixGetText(), and pixSetResolution().

◆ pixBestCorrelation()

l_ok pixBestCorrelation ( PIX pix1,
PIX pix2,
l_int32  area1,
l_int32  area2,
l_int32  etransx,
l_int32  etransy,
l_int32  maxshift,
l_int32 *  tab8,
l_int32 *  pdelx,
l_int32 *  pdely,
l_float32 *  pscore,
l_int32  debugflag 
)

pixBestCorrelation()

Parameters
[in]pix11 bpp
[in]pix21 bpp
[in]area1number of on pixels in pix1
[in]area2number of on pixels in pix2
[in]etransxestimated x translation of pix2 to align with pix1
[in]etransyestimated y translation of pix2 to align with pix1
[in]maxshiftmax x and y shift of pix2, around the estimated alignment location, relative to pix1
[in]tab8[optional] sum tab for ON pixels in byte; can be NULL
[out]pdelx[optional] best x shift of pix2 relative to pix1
[out]pdely[optional] best y shift of pix2 relative to pix1
[out]pscore[optional] maximum score found; can be NULL
[in]debugflag<= 0 to skip; positive to generate output. The integer is used to label the debug image.
Returns
0 if OK, 1 on error
Notes:
     (1) This maximizes the correlation score between two 1 bpp images,
         by starting with an estimate of the alignment
         (etransx, etransy) and computing the correlation around this.
         It optionally returns the shift (delx, dely) that maximizes
         the correlation score when pix2 is shifted by this amount
         relative to pix1.
     (2) Get the centroids of pix1 and pix2, using pixCentroid(),
         to compute (etransx, etransy).  Get the areas using
         pixCountPixels().
     (3) The centroid of pix2 is shifted with respect to the centroid
         of pix1 by all values between -maxshiftx and maxshiftx,
         and likewise for the y shifts.  Therefore, the number of
         correlations computed is:
              (2 * maxshiftx + 1) * (2 * maxshifty + 1)
         Consequently, if pix1 and pix2 are large, you should do this
         in a coarse-to-fine sequence.  See the use of this function
         in pixCompareWithTranslation().

Definition at line 3531 of file compare.c.

Referenced by pixCompareWithTranslation().

◆ pixCentroid8()

l_ok pixCentroid8 ( PIX pixs,
l_int32  factor,
l_float32 *  pcx,
l_float32 *  pcy 
)

pixCentroid8()

Parameters
[in]pixs8 bpp
[in]factorsubsampling factor; >= 1
[out]pcxx value of centroid
[out]pcyy value of centroid
Returns
0 if OK, 1 on error
Notes:
     (1) This first does a photometric inversion (black = 255, white = 0).
         It then finds the centroid of the result.  The inversion is
         done because white is usually background, so the centroid
         is computed based on the "foreground" gray pixels, and the
         darker the pixel, the more weight it is given.

Definition at line 2436 of file compare.c.

Referenced by pixCropAlignedToCentroid(), and pixPadToCenterCentroid().

◆ pixCompareBinary()

l_ok pixCompareBinary ( PIX pix1,
PIX pix2,
l_int32  comptype,
l_float32 *  pfract,
PIX **  ppixdiff 
)

pixCompareBinary()

Parameters
[in]pix11 bpp
[in]pix21 bpp
[in]comptypeL_COMPARE_XOR, L_COMPARE_SUBTRACT
[out]pfractfraction of pixels that are different
[out]ppixdiff[optional] pix of difference
Returns
0 if OK; 1 on error
Notes:
     (1) The two images are aligned at the UL corner, and do not
         need to be the same size.
     (2) If using L_COMPARE_SUBTRACT, pix2 is subtracted from pix1.
     (3) The total number of pixels is determined by pix1.
     (4) On error, the returned fraction is 1.0.

Definition at line 719 of file compare.c.

◆ pixCompareGray()

l_ok pixCompareGray ( PIX pix1,
PIX pix2,
l_int32  comptype,
l_int32  plottype,
l_int32 *  psame,
l_float32 *  pdiff,
l_float32 *  prmsdiff,
PIX **  ppixdiff 
)

pixCompareGray()

Parameters
[in]pix18 or 16 bpp, not cmapped
[in]pix28 or 16 bpp, not cmapped
[in]comptypeL_COMPARE_SUBTRACT, L_COMPARE_ABS_DIFF
[in]plottypegplot plot output type, or 0 for no plot
[out]psame[optional] 1 if pixel values are identical
[out]pdiff[optional] average difference
[out]prmsdiff[optional] rms of difference
[out]ppixdiff[optional] pix of difference
Returns
0 if OK; 1 on error
Notes:
     (1) See pixCompareGrayOrRGB() for details.
     (2) Use pixCompareGrayOrRGB() if the input pix are colormapped.
     (3) Note: setting plottype > 0 can result in writing named
               output files.

Definition at line 882 of file compare.c.

◆ pixCompareGrayByHisto()

l_ok pixCompareGrayByHisto ( PIX pix1,
PIX pix2,
BOX box1,
BOX box2,
l_float32  minratio,
l_int32  maxgray,
l_int32  factor,
l_int32  n,
l_float32 *  pscore,
l_int32  debugflag 
)

pixCompareGrayByHisto()

Parameters
[in]pix1,pix2any depth; colormap OK
[in]box1,box2[optional] region selected from each; can be null
[in]minratiorequiring sizes be compatible; < 1.0
[in]maxgraymax value to keep in histo; >= 200, 255 to keep all
[in]factorsubsampling factor; >= 1
[in]nin range {1, ... 7}. n^2 is the maximum number of subregions for histograms; typ. n = 3.
[out]pscoresimilarity score of histograms
[in]debugflag1 for debug output; 0 for no debugging
Returns
0 if OK, 1 on error
Notes:
     (1) This function compares two grayscale photo regions.  It can
         do it with a single histogram from each region, or with a
         set of spatially aligned histograms.  For both cases,
         align the regions using the centroid of the inverse image,
         and crop to the smallest of the two.
     (2) The parameter n specifies the "side" of an n x n grid
         of subimages.  If the subimages have an aspect ratio larger
         than 2, the grid will change, using n^2 as a maximum for
         the number of subimages.  For example, if n == 3, but the
         image is 600 x 200 pixels, a 3x3 grid would have subimages
         of 200 x 67 pixels, which is more than 2:1, so we change
         to a 4x2 grid where each subimage has 150 x 100 pixels.
     (3) An initial filter gives score = 0 if the ratio of widths
         and heights (smallest / largest) does not exceed a
         threshold minratio.  This must be between 0.5 and 1.0.
         If set at 1.0, both images must be exactly the same size.
         A typical value for minratio is 0.9.
     (4) The lightest values in the histogram can be disregarded.
         Set maxgray to the lightest value to be kept.  For example,
         to eliminate white (255), set maxgray = 254.  maxgray must
         be >= 200.
     (5) For an efficient representation of the histogram, normalize
         using a multiplicative factor so that the number in the
         maximum bucket is 255.  It then takes 256 bytes to store.
     (6) When comparing the histograms of two regions:
         ~ Use maxgray = 254 to ignore the white pixels, the number
           of which may be sensitive to the crop region if the pixels
           outside that region are white.
         ~ Use the Earth Mover distance (EMD), with the histograms
           normalized so that the sum over bins is the same.
           Further normalize by dividing by 255, so that the result
           is in [0.0 ... 1.0].
     (7) Get a similarity score S = 1.0 - k * D, where
           k is a constant, say in the range 5-10
           D = normalized EMD
         and for multiple tiles, take the Min(S) to be the final score.
         Using aligned tiles gives protection against accidental
         similarity of the overall grayscale histograms.
         A small number of aligned tiles works well.
     (8) With debug on, you get a pdf that shows, for each tile,
         the images, histograms and score.
     (9) When to use:
         (a) Because this function should not be used on text or
             line graphics, which can give false positive results
             (i.e., high scores for different images), the input
             images should be filtered.
         (b) To filter, first use pixDecideIfText().  If that function
             says the image is text, do not use it.  If the function
             says it is not text, it still may be line graphics, and
             in that case, use:
                pixGetGrayHistogramTiled()
                grayInterHistogramStats()
             to determine whether it is photo or line graphics.

Definition at line 2908 of file compare.c.

References boxDestroy(), boxGetGeometry(), L_INSERT, lept_mkdir(), pixaAddPix(), pixaCreate(), pixaDestroy(), pixaDisplayTiledInRows(), pixClipRectangle(), pixClone(), pixCompareTilesByHisto(), pixConvertTo32(), pixConvertTo8(), pixCropAlignedToCentroid(), pixDestroy(), pixGetDimensions(), pixRenderBoxArb(), and pixScaleToSize().

◆ pixCompareGrayOrRGB()

l_ok pixCompareGrayOrRGB ( PIX pix1,
PIX pix2,
l_int32  comptype,
l_int32  plottype,
l_int32 *  psame,
l_float32 *  pdiff,
l_float32 *  prmsdiff,
PIX **  ppixdiff 
)

pixCompareGrayOrRGB()

Parameters
[in]pix12,4,8,16 bpp gray, 32 bpp rgb, or colormapped
[in]pix22,4,8,16 bpp gray, 32 bpp rgb, or colormapped
[in]comptypeL_COMPARE_SUBTRACT, L_COMPARE_ABS_DIFF
[in]plottypegplot plot output type, or 0 for no plot
[out]psame[optional] 1 if pixel values are identical
[out]pdiff[optional] average difference
[out]prmsdiff[optional] rms of difference
[out]ppixdiff[optional] pix of difference
Returns
0 if OK; 1 on error
Notes:
     (1) The two images are aligned at the UL corner, and do not
         need to be the same size.  If they are not the same size,
         the comparison will be made over overlapping pixels.
     (2) If there is a colormap, it is removed and the result
         is either gray or RGB depending on the colormap.
     (3) If RGB, each component is compared separately.
     (4) If type is L_COMPARE_ABS_DIFF, pix2 is subtracted from pix1
         and the absolute value is taken.
     (5) If type is L_COMPARE_SUBTRACT, pix2 is subtracted from pix1
         and the result is clipped to 0.
     (6) The plot output types are specified in gplot.h.
         Use 0 if no difference plot is to be made.
     (7) If the images are pixelwise identical, no difference
         plot is made, even if requested.  The result (TRUE or FALSE)
         is optionally returned in the parameter 'same'.
     (8) The average difference (either subtracting or absolute value)
         is optionally returned in the parameter 'diff'.
     (9) The RMS difference is optionally returned in the
         parameter 'rmsdiff'.  For RGB, we return the average of
         the RMS differences for each of the components.
    (10) Because pixel values are compared, pix1 and pix2 can be equal when:
         * they are both gray with different depth
         * one is colormapped and the other is not
         * they are both colormapped and have different size colormaps

Definition at line 799 of file compare.c.

◆ pixComparePhotoRegionsByHisto()

l_ok pixComparePhotoRegionsByHisto ( PIX pix1,
PIX pix2,
BOX box1,
BOX box2,
l_float32  minratio,
l_int32  factor,
l_int32  n,
l_float32 *  pscore,
l_int32  debugflag 
)

pixComparePhotoRegionsByHisto()

Parameters
[in]pix1,pix2any depth; colormap OK
[in]box1,box2[optional] photo regions from each; can be null
[in]minratiorequiring sizes be compatible; < 1.0
[in]factorsubsampling factor; >= 1
[in]nin range {1, ... 7}. n^2 is the maximum number of subregions for histograms; typ. n = 3.
[out]pscoresimilarity score of histograms
[in]debugflag1 for debug output; 0 for no debugging
Returns
0 if OK, 1 on error
Notes:
     (1) This function compares two grayscale photo regions.  If a
         box is given, the region is clipped; otherwise assume
         the entire images are photo regions.  This is done with a
         set of not more than n^2 spatially aligned histograms, which are
         aligned using the centroid of the inverse image.
     (2) The parameter n specifies the "side" of an n x n grid
         of subimages.  If the subimages have an aspect ratio larger
         than 2, the grid will change, using n^2 as a maximum for
         the number of subimages.  For example, if n == 3, but the
         image is 600 x 200 pixels, a 3x3 grid would have subimages
         of 200 x 67 pixels, which is more than 2:1, so we change
         to a 4x2 grid where each subimage has 150 x 100 pixels.
     (3) An initial filter gives score = 0 if the ratio of widths
         and heights (smallest / largest) does not exceed a
         threshold minratio.  This must be between 0.5 and 1.0.
         If set at 1.0, both images must be exactly the same size.
         A typical value for minratio is 0.9.
     (4) Because this function should not be used on text or
         line graphics, which can give false positive results
         (i.e., high scores for different images), filter the images
         using pixGenPhotoHistos(), which returns tiled histograms
         only if an image is not text and comparison is expected
         to work with histograms.  If either image fails the test,
         the comparison returns a score of 0.0.
     (5) The white value counts in the histograms are removed; they
         are typically pixels that were padded to achieve alignment.
     (6) For an efficient representation of the histogram, normalize
         using a multiplicative factor so that the number in the
         maximum bucket is 255.  It then takes 256 bytes to store.
     (7) When comparing the histograms of two regions, use the
         Earth Mover distance (EMD), with the histograms normalized
         so that the sum over bins is the same.  Further normalize
         by dividing by 255, so that the result is in [0.0 ... 1.0].
     (8) Get a similarity score S = 1.0 - k * D, where
           k is a constant, say in the range 5-10
           D = normalized EMD
         and for multiple tiles, take the Min(S) to be the final score.
         Using aligned tiles gives protection against accidental
         similarity of the overall grayscale histograms.
         A small number of aligned tiles works well.
     (9) With debug on, you get a pdf that shows, for each tile,
         the images, histograms and score.

Definition at line 2152 of file compare.c.

References boxGetGeometry(), compareTilesByHisto(), lept_mkdir(), pixaCreate(), pixaDestroy(), pixClipRectangle(), pixClone(), pixDestroy(), pixGenPhotoHistos(), and pixGetDimensions().

◆ pixCompareRankDifference()

NUMA* pixCompareRankDifference ( PIX pix1,
PIX pix2,
l_int32  factor 
)

pixCompareRankDifference()

Parameters
[in]pix18 bpp gray or 32 bpp rgb, or colormapped
[in]pix28 bpp gray or 32 bpp rgb, or colormapped
[in]factorsubsampling factor; use 0 or 1 for no subsampling
Returns
narank numa of rank difference, or NULL on error
Notes:
     (1) This answers the question: if the pixel values in each
         component are compared by absolute difference, for
         any value of difference, what is the fraction of
         pixel pairs that have a difference of this magnitude
         or greater.  For a difference of 0, the fraction is 1.0.
         In this sense, it is a mapping from pixel difference to
         rank order of difference.
     (2) The two images are aligned at the UL corner, and do not
         need to be the same size.  If they are not the same size,
         the comparison will be made over overlapping pixels.
     (3) If there is a colormap, it is removed and the result
         is either gray or RGB depending on the colormap.
     (4) If RGB, pixel differences for each component are aggregated
         into a single histogram.

Definition at line 1241 of file compare.c.

References L_NOCOPY, numaCreate(), numaDestroy(), numaGetFArray(), numaNormalizeHistogram(), numaSetCount(), and pixGetDifferenceHistogram().

◆ pixCompareRGB()

l_ok pixCompareRGB ( PIX pix1,
PIX pix2,
l_int32  comptype,
l_int32  plottype,
l_int32 *  psame,
l_float32 *  pdiff,
l_float32 *  prmsdiff,
PIX **  ppixdiff 
)

pixCompareRGB()

Parameters
[in]pix132 bpp rgb
[in]pix232 bpp rgb
[in]comptypeL_COMPARE_SUBTRACT, L_COMPARE_ABS_DIFF
[in]plottypegplot plot output type, or 0 for no plot
[out]psame[optional] 1 if pixel values are identical
[out]pdiff[optional] average difference
[out]prmsdiff[optional] rms of difference
[out]ppixdiff[optional] pix of difference
Returns
0 if OK; 1 on error
Notes:
     (1) See pixCompareGrayOrRGB() for details.
     (2) Note: setting plottype > 0 can result in writing named
               output files.

Definition at line 991 of file compare.c.

◆ pixCompareTiled()

l_ok pixCompareTiled ( PIX pix1,
PIX pix2,
l_int32  sx,
l_int32  sy,
l_int32  type,
PIX **  ppixdiff 
)

pixCompareTiled()

Parameters
[in]pix18 bpp or 32 bpp rgb
[in]pix28 bpp 32 bpp rgb
[in]sx,sytile size; must be > 1 in each dimension
[in]typeL_MEAN_ABSVAL or L_ROOT_MEAN_SQUARE
[out]ppixdiffpix of difference
Returns
0 if OK; 1 on error
Notes:
     (1) With L_MEAN_ABSVAL, we compute for each tile the
         average abs value of the pixel component difference between
         the two (aligned) images.  With L_ROOT_MEAN_SQUARE, we
         compute instead the rms difference over all components.
     (2) The two input pix must be the same depth.  Comparison is made
         using UL corner alignment.
     (3) For 32 bpp, the distance between corresponding tiles
         is found by averaging the measured difference over all three
         components of each pixel in the tile.
     (4) The result, pixdiff, contains one pixel for each source tile.

Definition at line 1147 of file compare.c.

◆ pixCompareTilesByHisto()

static l_ok pixCompareTilesByHisto ( PIX pix1,
PIX pix2,
l_int32  maxgray,
l_int32  factor,
l_int32  n,
l_float32 *  pscore,
PIXA pixadebug 
)
static

pixCompareTilesByHisto()

Parameters
[in]pix1,pix28 bpp
[in]maxgraymax value to keep in histo; 255 to keep all
[in]factorsubsampling factor; >= 1
[in]nsee pixCompareGrayByHisto()
[out]pscoresimilarity score of histograms
[in]pixadebug[optional] use only for debug output
Returns
0 if OK, 1 on error
Notes:
     (1) This static function is only called from pixCompareGrayByHisto().
         The input images have been converted to 8 bpp if necessary,
         aligned and cropped.
     (2) The input pixadebug is null unless debug output is requested.
     (3) See pixCompareGrayByHisto() for details.

Definition at line 3035 of file compare.c.

References bmfCreate(), findHistoGridDimensions(), gplotSimple2(), L_CLONE, numaCreate(), numaGetMax(), numaSetValue(), numaTransform(), numaWindowedMean(), pixaGetPix(), pixaSplitPix(), pixGetDimensions(), and pixGetGrayHistogram().

Referenced by pixCompareGrayByHisto().

◆ pixCompareWithTranslation()

l_ok pixCompareWithTranslation ( PIX pix1,
PIX pix2,
l_int32  thresh,
l_int32 *  pdelx,
l_int32 *  pdely,
l_float32 *  pscore,
l_int32  debugflag 
)

pixCompareWithTranslation()

Parameters
[in]pix1,pix2any depth; colormap OK
[in]threshthreshold for converting to 1 bpp
[out]pdelxx translation on pix2 to align with pix1
[out]pdelyy translation on pix2 to align with pix1
[out]pscorecorrelation score at best alignment
[in]debugflag1 for debug output; 0 for no debugging
Returns
0 if OK, 1 on error
Notes:
     (1) This does a coarse-to-fine search for best translational
         alignment of two images, measured by a scoring function
         that is the correlation between the fg pixels.
     (2) The threshold is used if the images aren't 1 bpp.
     (3) With debug on, you get a pdf that shows, as a grayscale
         image, the score as a function of shift from the initial
         estimate, for each of the four levels.  The shift is 0 at
         the center of the image.
     (4) With debug on, you also get a pdf that shows the
         difference at the best alignment between the two images,
         at each of the four levels.  The red and green pixels
         show locations where one image has a fg pixel and the
         other doesn't.  The black pixels are where both images
         have fg pixels, and white pixels are where neither image
         has fg pixels.

Definition at line 3377 of file compare.c.

References convertFilesToPdf(), L_BRING_IN_WHITE, L_CLONE, L_FLATE_ENCODE, L_INSERT, lept_roundftoi(), lept_stderr(), makePixelCentroidTab8(), makePixelSumTab8(), makeSubsampleTab2x(), pixaAddPix(), pixaConvertToPdf(), pixaCreate(), pixaDestroy(), pixaGetPix(), pixBestCorrelation(), pixCentroid(), pixConvertTo1(), pixCountPixels(), pixDestroy(), pixDisplayDiffBinary(), pixExpandReplicate(), pixRasteropIP(), and pixReduceRankBinary2().

◆ pixCorrelationBinary()

l_ok pixCorrelationBinary ( PIX pix1,
PIX pix2,
l_float32 *  pval 
)

pixCorrelationBinary()

Parameters
[in]pix11 bpp
[in]pix21 bpp
[out]pvalcorrelation
Returns
0 if OK; 1 on error
Notes:
     (1) The correlation is a number between 0.0 and 1.0,
         based on foreground similarity:
                          (|1 AND 2|)**2
           correlation =  --------------
                            |1| * |2|
         where |x| is the count of foreground pixels in image x.
         If the images are identical, this is 1.0.
         If they have no fg pixels in common, this is 0.0.
         If one or both images have no fg pixels, the correlation is 0.0.
     (2) Typically the two images are of equal size, but this
         is not enforced.  Instead, the UL corners are aligned.

Definition at line 604 of file compare.c.

References makePixelSumTab8(), pixAnd(), pixCountPixels(), and pixDestroy().

◆ pixCropAlignedToCentroid()

l_ok pixCropAlignedToCentroid ( PIX pix1,
PIX pix2,
l_int32  factor,
BOX **  pbox1,
BOX **  pbox2 
)

pixCropAlignedToCentroid()

Parameters
[in]pix1,pix2any depth; colormap OK
[in]factorsubsampling; >= 1
[out]pbox1crop box for pix1
[out]pbox2crop box for pix2
Returns
0 if OK, 1 on error
Notes:
     (1) This finds the maximum crop boxes for two 8 bpp images when
         their centroids of their photometric inverses are aligned.
         Black pixels have weight 255; white pixels have weight 0.

Definition at line 3165 of file compare.c.

References boxCreate(), pixCentroid8(), pixConvertTo8(), pixDestroy(), and pixGetDimensions().

Referenced by pixCompareGrayByHisto().

◆ pixDecideIfPhotoImage()

l_ok pixDecideIfPhotoImage ( PIX pix,
l_int32  factor,
l_float32  thresh,
l_int32  n,
NUMAA **  pnaa,
PIXA pixadebug 
)

pixDecideIfPhotoImage()

Parameters
[in]pix8 bpp, centroid in center
[in]factorsubsampling for histograms; >= 1
[in]threshthreshold for photo/text; use 0 for default
[in]nin range {1, ... 7}. n^2 is the maximum number of subregions for histograms; typ. n = 3.
[out]pnaaarray of normalized histograms
[in]pixadebug[optional] use only for debug output
Returns
0 if OK, 1 on error
Notes:
     (1) The input image must be 8 bpp (no colormap), and padded with
         white pixels so the centroid of photo-inverted pixels is at
         the center of the image.
     (2) The parameter n specifies the "side" of the n x n grid
         of subimages.  If the subimages have an aspect ratio larger
         than 2, the grid will change, using n^2 as a maximum for
         the number of subimages.  For example, if n == 3, but the
         image is 600 x 200 pixels, a 3x3 grid would have subimages
         of 200 x 67 pixels, which is more than 2:1, so we change
         to a 4x2 grid where each subimage has 150 x 100 pixels.
     (3) If the pix is not almost certainly a photoimage, the returned
         histograms (naa) are null.
     (4) If histograms are generated, the white (255) count is set
         to 0.  This removes all pixels values above 230, including
         white padding from the centroid matching operation, from
         consideration.  The resulting histograms are then normalized
         so the maximum count is 255.
     (5) Default for thresh is 1.3; this seems sufficiently conservative.
     (6) Use pixadebug == NULL unless debug output is requested.

Definition at line 2522 of file compare.c.

◆ pixDisplayDiffBinary()

PIX* pixDisplayDiffBinary ( PIX pix1,
PIX pix2 
)

pixDisplayDiffBinary()

Parameters
[in]pix11 bpp
[in]pix21 bpp
Returns
pixd 4 bpp cmapped, or NULL on error
Notes:
     (1) This gives a color representation of the difference between
         pix1 and pix2.  The color difference depends on the order.
         The pixels in pixd have 4 colors:
          * unchanged:  black (on), white (off)
          * on in pix1, off in pix2: red
          * on in pix2, off in pix1: green
     (2) This aligns the UL corners of pix1 and pix2, and crops
         to the overlapping pixels.

Definition at line 662 of file compare.c.

References pixAnd(), pixcmapAddColor(), pixcmapCreate(), pixCreate(), pixDestroy(), pixGetDimensions(), pixPaintThroughMask(), pixSetColormap(), and pixSubtract().

Referenced by pixCompareWithTranslation().

◆ pixEqual()

l_ok pixEqual ( PIX pix1,
PIX pix2,
l_int32 *  psame 
)

pixEqual()

Parameters
[in]pix1
[in]pix2
[out]psame1 if same; 0 if different
Returns
0 if OK; 1 on error
Notes:
     (1) Equality is defined as having the same pixel values for
         each respective image pixel.
     (2) This works on two pix of any depth.  If one or both pix
         have a colormap, the depths can be different and the
         two pix can still be equal.
     (3) This ignores the alpha component for 32 bpp images.
     (4) If both pix have colormaps and the depths are equal,
         use the pixEqualWithCmap() function, which does a fast
         comparison if the colormaps are identical and a relatively
         slow comparison otherwise.
     (5) In all other cases, any existing colormaps must first be
         removed before doing pixel comparison.  After the colormaps
         are removed, the resulting two images must have the same depth.
         The "lowest common denominator" is RGB, but this is only
         chosen when necessary, or when both have colormaps but
         different depths.
     (6) For images without colormaps that are not 32 bpp, all bits
         in the image part of the data array must be identical.

Definition at line 156 of file compare.c.

References pixEqualWithAlpha().

Referenced by pixaEqual(), and regTestComparePix().

◆ pixEqualWithAlpha()

l_ok pixEqualWithAlpha ( PIX pix1,
PIX pix2,
l_int32  use_alpha,
l_int32 *  psame 
)

pixEqualWithAlpha()

Parameters
[in]pix1
[in]pix2
[in]use_alpha1 to compare alpha in RGBA; 0 to ignore
[out]psame1 if same; 0 if different
Returns
0 if OK; 1 on error
Notes:
     (1) See notes in pixEqual().
     (2) This is more general than pixEqual(), in that for 32 bpp
         RGBA images, where spp = 4, you can optionally include
         the alpha component in the comparison.

Definition at line 182 of file compare.c.

References pixGetDimensions().

Referenced by pixEqual().

◆ pixEqualWithCmap()

l_ok pixEqualWithCmap ( PIX pix1,
PIX pix2,
l_int32 *  psame 
)

pixEqualWithCmap()

Parameters
[in]pix1
[in]pix2
[out]psame
Returns
0 if OK, 1 on error
Notes:
     (1) This returns same = TRUE if the images have identical content.
     (2) Both pix must have a colormap, and be of equal size and depth.
         If these conditions are not satisfied, it is not an error;
         the returned result is same = FALSE.
     (3) We then check whether the colormaps are the same; if so,
         the comparison proceeds 32 bits at a time.
     (4) If the colormaps are different, the comparison is done by
         slow brute force.

Definition at line 384 of file compare.c.

References pixSizesEqual().

◆ pixGenPhotoHistos()

l_ok pixGenPhotoHistos ( PIX pixs,
BOX box,
l_int32  factor,
l_float32  thresh,
l_int32  n,
NUMAA **  pnaa,
l_int32 *  pw,
l_int32 *  ph,
l_int32  debugindex 
)

pixGenPhotoHistos()

Parameters
[in]pixsdepth > 1 bpp; colormap OK
[in]box[optional] region to be selected; can be null
[in]factorsubsampling; >= 1
[in]threshthreshold for photo/text; use 0 for default
[in]nin range {1, ... 7}. n^2 is the maximum number of subregions for histograms; typ. n = 3.
[out]pnaanx * ny 256-entry gray histograms
[out]pwwidth of image used to make histograms
[out]phheight of image used to make histograms
[in]debugindex0 for no debugging; positive integer otherwise
Returns
0 if OK, 1 on error
Notes:
     (1) This crops and converts to 8 bpp if necessary.  It adds a
         minimal white boundary such that the centroid of the
         photo-inverted image is in the center. This allows
         automatic alignment with histograms of other image regions.
     (2) The parameter n specifies the "side" of the n x n grid
         of subimages.  If the subimages have an aspect ratio larger
         than 2, the grid will change, using n^2 as a maximum for
         the number of subimages.  For example, if n == 3, but the
         image is 600 x 200 pixels, a 3x3 grid would have subimages
         of 200 x 67 pixels, which is more than 2:1, so we change
         to a 4x2 grid where each subimage has 150 x 100 pixels.
     (3) The white value in the histogram is removed, because of
         the padding.
     (4) Use 0 for conservative default (1.3) for thresh.
     (5) For an efficient representation of the histogram, normalize
         using a multiplicative factor so that the number in the
         maximum bucket is 255.  It then takes 256 bytes to store.
     (6) With debugindex > 0, this makes a pdf that shows, for each tile,
         the images and histograms.

Definition at line 2269 of file compare.c.

Referenced by pixaComparePhotoRegionsByHisto(), and pixComparePhotoRegionsByHisto().

◆ pixGetDifferenceHistogram()

NUMA* pixGetDifferenceHistogram ( PIX pix1,
PIX pix2,
l_int32  factor 
)

pixGetDifferenceHistogram()

Parameters
[in]pix18 bpp gray or 32 bpp rgb, or colormapped
[in]pix28 bpp gray or 32 bpp rgb, or colormapped
[in]factorsubsampling factor; use 0 or 1 for no subsampling
Returns
na Numa of histogram of differences, or NULL on error
Notes:
     (1) The two images are aligned at the UL corner, and do not
         need to be the same size.  If they are not the same size,
         the comparison will be made over overlapping pixels.
     (2) If there is a colormap, it is removed and the result
         is either gray or RGB depending on the colormap.
     (3) If RGB, the maximum difference between pixel components is
         saved in the histogram.

Definition at line 1507 of file compare.c.

Referenced by pixCompareRankDifference(), and pixGetDifferenceStats().

◆ pixGetDifferenceStats()

l_ok pixGetDifferenceStats ( PIX pix1,
PIX pix2,
l_int32  factor,
l_int32  mindiff,
l_float32 *  pfractdiff,
l_float32 *  pavediff,
l_int32  details 
)

pixGetDifferenceStats()

Parameters
[in]pix18 bpp gray or 32 bpp rgb, or colormapped
[in]pix28 bpp gray or 32 bpp rgb, or colormapped
[in]factorsubsampling factor; use 0 or 1 for no subsampling
[in]mindiffminimum pixel difference to be counted; > 0
[out]pfractdifffraction of pixels with diff greater than or equal to mindiff
[out]pavediffaverage difference of pixels with diff greater than or equal to mindiff, less mindiff
[in]detailsuse 1 to give normalized histogram and other data
Returns
0 if OK, 1 on error
Notes:
     (1) This takes a threshold mindiff and describes the difference
         between two images in terms of two numbers:
           (a) the fraction of pixels, fractdiff, whose difference
               equals or exceeds the threshold mindiff, and
           (b) the average value avediff of the difference in pixel value
               for the pixels in the set given by (a), after you subtract
               mindiff.  The reason for subtracting mindiff is that
               you then get a useful measure for the rate of falloff
               of the distribution for larger differences.  For example,
               if mindiff = 10 and you find that avediff = 2.5, it
               says that of the pixels with diff > 10, the average of
               their diffs is just mindiff + 2.5 = 12.5.  This is a
               fast falloff in the histogram with increasing difference.
     (2) The two images are aligned at the UL corner, and do not
         need to be the same size.  If they are not the same size,
         the comparison will be made over overlapping pixels.
     (3) If there is a colormap, it is removed and the result
         is either gray or RGB depending on the colormap.
     (4) If RGB, the maximum difference between pixel components is
         saved in the histogram.
     (5) Set details == 1 to see the difference histogram and get
         an output that shows for each value of mindiff, what are the
         minimum values required for fractdiff and avediff in order
         that the two pix will be considered similar.

Definition at line 1405 of file compare.c.

References gplotSimple1(), L_NOCOPY, lept_mkdir(), numaClipToInterval(), numaDestroy(), numaGetFArray(), numaGetNonzeroRange(), numaNormalizeHistogram(), and pixGetDifferenceHistogram().

Referenced by pixTestForSimilarity().

◆ pixGetPerceptualDiff()

l_ok pixGetPerceptualDiff ( PIX pixs1,
PIX pixs2,
l_int32  sampling,
l_int32  dilation,
l_int32  mindiff,
l_float32 *  pfract,
PIX **  ppixdiff1,
PIX **  ppixdiff2 
)

pixGetPerceptualDiff()

Parameters
[in]pixs18 bpp gray or 32 bpp rgb, or colormapped
[in]pixs28 bpp gray or 32 bpp rgb, or colormapped
[in]samplingsubsampling factor; use 0 or 1 for no subsampling
[in]dilationsize of grayscale or color Sel; odd
[in]mindiffminimum pixel difference to be counted; > 0
[out]pfractfraction of pixels with diff greater than mindiff
[out]ppixdiff1[optional] showing difference (gray or color)
[out]ppixdiff2[optional] showing pixels of sufficient diff
Returns
0 if OK, 1 on error
Notes:
     (1) This takes 2 pix and determines, using 2 input parameters:
          * dilation specifies the amount of grayscale or color
            dilation to apply to the images, to compensate for
            a small amount of misregistration.  A typical number might
            be 5, which uses a 5x5 Sel.  Grayscale dilation expands
            lighter pixels into darker pixel regions.
          * mindiff determines the threshold on the difference in
            pixel values to be counted -- two pixels are not similar
            if their difference in value is at least mindiff.  For
            color pixels, we use the maximum component difference.
     (2) The pixelwise comparison is always done with the UL corners
         aligned.  The sizes of pix1 and pix2 need not be the same,
         although in practice it can be useful to scale to the same size.
     (3) If there is a colormap, it is removed and the result
         is either gray or RGB depending on the colormap.
     (4) Two optional diff images can be retrieved (typ. for debugging):
          pixdiff1: the gray or color difference
          pixdiff2: thresholded to 1 bpp for pixels exceeding mindiff
     (5) The returned value of fract can be compared to some threshold,
         which is application dependent.
     (6) This method is in analogy to the two-sided hausdorff transform,
         except here it is for d > 1.  For d == 1 (see pixRankHaustest()),
         we verify that when one pix1 is dilated, it covers at least a
         given fraction of the pixels in pix2, and v.v.; in that
         case, the two pix are sufficiently similar.  Here, we
         do an analogous thing: subtract the dilated pix1 from pix2 to
         get a 1-sided hausdorff-like transform.  Then do it the
         other way.  Take the component-wise max of the two results,
         and threshold to get the fraction of pixels with a difference
         below the threshold.

Definition at line 1638 of file compare.c.

◆ pixGetPSNR()

l_ok pixGetPSNR ( PIX pix1,
PIX pix2,
l_int32  factor,
l_float32 *  ppsnr 
)

pixGetPSNR()

Parameters
[in]pix1,pix28 or 32 bpp; no colormap
[in]factorsampling factor; >= 1
[out]ppsnrpower signal/noise ratio difference
Returns
0 if OK, 1 on error
Notes:
     (1) This computes the power S/N ratio, in dB, for the difference
         between two images.  By convention, the power S/N
         for a grayscale image is ('log' == log base 10,
         and 'ln == log base e):
           PSNR = 10 * log((255/MSE)^2)
                = 4.3429 * ln((255/MSE)^2)
                = -4.3429 * ln((MSE/255)^2)
         where MSE is the mean squared error.
         Here are some examples:
            MSE             PSNR
            ---             ----
            10              28.1
            3               38.6
            1               48.1
            0.1             68.1
     (2) If pix1 and pix2 have the same pixel values, the MSE = 0.0
         and the PSNR is infinity.  For that case, this returns
         PSNR = 1000, which corresponds to the very small MSE of
         about 10^(-48).

Definition at line 1805 of file compare.c.

References pixSizesEqual().

◆ pixPadToCenterCentroid()

PIX* pixPadToCenterCentroid ( PIX pixs,
l_int32  factor 
)

pixPadToCenterCentroid()

Parameters
[in]pixsany depth, colormap OK
[in]factorsubsampling for centroid; >= 1
Returns
pixd padded with white pixels, or NULL on error.
Notes:
     (1) This add minimum white padding to an 8 bpp pix, such that
         the centroid of the photometric inverse is in the center of
         the resulting image.  Thus in computing the centroid,
         black pixels have weight 255, and white pixels have weight 0.

Definition at line 2382 of file compare.c.

References pixCentroid8(), pixConvertTo8(), pixCreate(), pixGetDimensions(), and pixSetAll().

◆ pixTestForSimilarity()

l_ok pixTestForSimilarity ( PIX pix1,
PIX pix2,
l_int32  factor,
l_int32  mindiff,
l_float32  maxfract,
l_float32  maxave,
l_int32 *  psimilar,
l_int32  details 
)

pixTestForSimilarity()

Parameters
[in]pix18 bpp gray or 32 bpp rgb, or colormapped
[in]pix28 bpp gray or 32 bpp rgb, or colormapped
[in]factorsubsampling factor; use 0 or 1 for no subsampling
[in]mindiffminimum pixel difference to be counted; > 0
[in]maxfractmaximum fraction of pixels allowed to have diff greater than or equal to mindiff
[in]maxavemaximum average difference of pixels allowed for pixels with diff greater than or equal to mindiff, after subtracting mindiff
[out]psimilar1 if similar, 0 otherwise
[in]detailsuse 1 to give normalized histogram and other data
Returns
0 if OK, 1 on error
Notes:
     (1) This takes 2 pix that are the same size and determines using
         3 input parameters if they are "similar".  The first parameter
         mindiff establishes a criterion of pixel-to-pixel similarity:
         two pixels are not similar if their difference in value is
         at least mindiff.  Then maxfract and maxave are thresholds
         on the number and distribution of dissimilar pixels
         allowed for the two pix to be similar.   If the pix are
         to be similar, neither threshold can be exceeded.
     (2) In setting the maxfract and maxave thresholds, you have
         these options:
           (a) Base the comparison only on maxfract.  Then set
               maxave = 0.0 or 256.0.  (If 0, we always ignore it.)
           (b) Base the comparison only on maxave.  Then set
               maxfract = 1.0.
           (c) Base the comparison on both thresholds.
     (3) Example of values that can be expected at mindiff = 15 when
         comparing lossless png encoding with jpeg encoding, q=75:
            (smoothish bg)       fractdiff = 0.01, avediff = 2.5
            (natural scene)      fractdiff = 0.13, avediff = 3.5
         To identify these images as 'similar', select maxfract
         and maxave to be upper bounds of what you expect.
     (4) See pixGetDifferenceStats() for a discussion of why we subtract
         mindiff from the computed average diff of the nonsimilar pixels
         to get the 'avediff' returned by that function.
     (5) If there is a colormap, it is removed and the result
         is either gray or RGB depending on the colormap.
     (6) If RGB, the maximum difference between pixel components is
         saved in the histogram.

Definition at line 1326 of file compare.c.

References pixGetDifferenceStats(), and pixSizesEqual().

Referenced by regTestCompareSimilarPix().

◆ pixUsesCmapColor()

l_ok pixUsesCmapColor ( PIX pixs,
l_int32 *  pcolor 
)

pixUsesCmapColor()

Parameters
[in]pixsany depth, colormap
[out]pcolorTRUE if color found
Returns
0 if OK, 1 on error
Notes:
     (1) This returns color = TRUE if three things are obtained:
         (a) the pix has a colormap
         (b) the colormap has at least one color entry
         (c) a color entry is actually used
     (2) It is used in pixEqual() for comparing two images, in a
         situation where it is required to know if the colormap
         has color entries that are actually used in the image.

Definition at line 538 of file compare.c.