#include <string.h>
#include "allheaders.h"

Functions
static char *	getRootNameFromArgv0 (const char *argv0)

l_ok	regTestSetup (l_int32 argc, char argv, L_REGPARAMS prp)

l_ok	regTestCleanup (L_REGPARAMS *rp)

l_ok	regTestCompareValues (L_REGPARAMS *rp, l_float32 val1, l_float32 val2, l_float32 delta)

l_ok	regTestCompareStrings (L_REGPARAMS rp, l_uint8 string1, size_t bytes1, l_uint8 *string2, size_t bytes2)

l_ok	regTestComparePix (L_REGPARAMS rp, PIX pix1, PIX *pix2)

l_ok	regTestCompareSimilarPix (L_REGPARAMS rp, PIX pix1, PIX *pix2, l_int32 mindiff, l_float32 maxfract, l_int32 printstats)

l_ok	regTestCheckFile (L_REGPARAMS rp, const char localname)

l_ok	regTestCompareFiles (L_REGPARAMS *rp, l_int32 index1, l_int32 index2)

l_ok	regTestWritePixAndCheck (L_REGPARAMS rp, PIX pix, l_int32 format)

l_ok	regTestWriteDataAndCheck (L_REGPARAMS rp, void data, size_t nbytes, const char *ext)

char *	regTestGenLocalFilename (L_REGPARAMS *rp, l_int32 index, l_int32 format)

Variables
l_int32	NumImageFileFormatExtensions

const char *	ImageFileFormatExtensions []

Detailed Description


      Regression test utilities
          l_int32    regTestSetup()
          l_int32    regTestCleanup()
          l_int32    regTestCompareValues()
          l_int32    regTestCompareStrings()
          l_int32    regTestComparePix()
          l_int32    regTestCompareSimilarPix()
          l_int32    regTestCheckFile()
          l_int32    regTestCompareFiles()
          l_int32    regTestWritePixAndCheck()
          l_int32    regTestWriteDataAndCheck()
          char      *regTestGenLocalFilename()

      Static function
          char      *getRootNameFromArgv0()

 These functions are for testing and development.  They are not intended
 for use with programs that run in a production environment, such as a
 cloud service with unrestricted access.

 See regutils.h for how to use this.  Here is a minimal setup:

 main(int argc, char **argv) {
 ...
 L_REGPARAMS  *rp;

     if (regTestSetup(argc, argv, &rp))
         return 1;
     ...
     regTestWritePixAndCheck(rp, pix, IFF_PNG);  // 0
     ...
     return regTestCleanup(rp);
 }

Definition in file regutils.c.

Function Documentation

◆ getRootNameFromArgv0()

static char * getRootNameFromArgv0 ( const char * argv0 )

static

getRootNameFromArgv0()

Parameters

[in] argv0

Returns: root name without the '_reg', or NULL on error

Notes:
     (1) For example, from psioseg_reg, we want to extract
         just 'psioseg' as the root.
     (2) In unix with autotools, the executable is not X,
         but ./.libs/lt-X.   So in addition to stripping out the
         last 4 characters of the tail, we have to check for
         the '-' and strip out the "lt-" prefix if we find it.

Definition at line 839 of file regutils.c.

Referenced by regTestSetup().

◆ regTestCheckFile()

l_ok regTestCheckFile	(	L_REGPARAMS *	rp,
		const char *	localname )

regTestCheckFile()

Parameters

[in]	rp	regtest parameters
[in]	localname	name of output file from reg test

Returns: 0 if OK, 1 on error Note: a failure in comparison is not an error

Notes:
     (1) This function does one of three things, depending on the mode:
          * "generate": makes a "golden" file as a copy of localname.
          * "compare": compares localname contents with the golden file
          * "display": this does nothing
     (2) The canonical format of the golden filenames is:
           /tmp/lept/golden/[root of main name]_golden.[index].
                                                      [ext of localname]
         e.g.,
            /tmp/lept/golden/maze_golden.0.png
     (3) The local file can be made in any subdirectory of /tmp/lept,
         including /tmp/lept/regout/.
     (4) It is important to add an extension to the local name, such as
            /tmp/lept/maze/file1.png    (extension ".png")
         because the extension is added to the name of the golden file.

Definition at line 490 of file regutils.c.

References L_RegParams::fp, L_RegParams::index, L_RegParams::mode, L_RegParams::success, and L_RegParams::testname.

Referenced by regTestWriteDataAndCheck(), and regTestWritePixAndCheck().

◆ regTestCleanup()

l_ok regTestCleanup ( L_REGPARAMS * rp )

regTestCleanup()

Parameters

[in] rp regression test parameters

Returns: 0 if OK, 1 on error

Notes:
     (1) This copies anything written to the temporary file to the
         output file /tmp/lept/reg_results.txt.

Definition at line 208 of file regutils.c.

References L_RegParams::fp, L_RegParams::success, L_RegParams::tempfile, L_RegParams::testname, and L_RegParams::tstart.

◆ regTestCompareFiles()

l_ok regTestCompareFiles	(	L_REGPARAMS *	rp,
		l_int32	index1,
		l_int32	index2 )

regTestCompareFiles()

Parameters

[in]	rp	regtest parameters
[in]	index1	of one output file from reg test
[in]	index2	of another output file from reg test

Returns: 0 if OK, 1 on error Note: a failure in comparison is not an error

Notes:
     (1) This only does something in "compare" mode.
     (2) The canonical format of the golden filenames is:
           /tmp/lept/golden/[root of main name]_golden.[index].
                                                     [ext of localname]
         e.g.,
           /tmp/lept/golden/maze_golden.0.png

Definition at line 596 of file regutils.c.

References L_RegParams::fp, L_RegParams::index, L_COPY, L_RegParams::mode, L_RegParams::success, and L_RegParams::testname.

◆ regTestComparePix()

l_ok regTestComparePix	(	L_REGPARAMS *	rp,
		PIX *	pix1,
		PIX *	pix2 )

regTestComparePix()

Parameters

[in]	rp	regtest parameters
[in]	pix1,pix2	to be tested for equality

Returns: 0 if OK, 1 on error Note: a failure in comparison is not an error

Notes:
     (1) This function compares two pix for equality.  On failure,
         this writes to stderr.

Definition at line 367 of file regutils.c.

References L_RegParams::fp, L_RegParams::index, L_RegParams::success, and L_RegParams::testname.

◆ regTestCompareSimilarPix()

l_ok regTestCompareSimilarPix	(	L_REGPARAMS *	rp,
		PIX *	pix1,
		PIX *	pix2,
		l_int32	mindiff,
		l_float32	maxfract,
		l_int32	printstats )

regTestCompareSimilarPix()

Parameters

[in]	rp	regtest parameters
[in]	pix1,pix2	to be tested for near equality
[in]	mindiff	minimum pixel difference to be counted; > 0
[in]	maxfract	maximum fraction of pixels allowed to have diff greater than or equal to mindiff
[in]	printstats	use 1 to print normalized histogram to stderr

Returns: 0 if OK, 1 on error Note: a failure in similarity comparison is not an error

Notes:
     (1) This function compares two pix for near equality.  On failure,
         this writes to stderr.
     (2) The pix are similar if the fraction of non-conforming pixels
         does not exceed maxfract.  Pixels are non-conforming if
         the difference in pixel values equals or exceeds mindiff.
         Typical values might be mindiff = 15 and maxfract = 0.01.
     (3) The input images must have the same size and depth.  The
         pixels for comparison are typically subsampled from the images.
     (4) Normally, use printstats = 0.  In debugging mode, to see
         the relation between mindiff and the minimum value of
         maxfract for success, set this to 1.

Definition at line 425 of file regutils.c.

References L_RegParams::fp, L_RegParams::index, L_RegParams::success, and L_RegParams::testname.

◆ regTestCompareStrings()

l_ok regTestCompareStrings	(	L_REGPARAMS *	rp,
		l_uint8 *	string1,
		size_t	bytes1,
		l_uint8 *	string2,
		size_t	bytes2 )

regTestCompareStrings()

Parameters

[in]	rp	regtest parameters
[in]	string1	typ. the expected string
[in]	bytes1	size of string1
[in]	string2	typ. the computed string
[in]	bytes2	size of string2

Returns: 0 if OK, 1 on error Note: a failure in comparison is not an error

Definition at line 312 of file regutils.c.

References L_RegParams::fp, L_RegParams::index, L_RegParams::success, and L_RegParams::testname.

◆ regTestCompareValues()

l_ok regTestCompareValues	(	L_REGPARAMS *	rp,
		l_float32	val1,
		l_float32	val2,
		l_float32	delta )

regTestCompareValues()

Parameters

[in]	rp	regtest parameters
[in]	val1	typ. the golden value
[in]	val2	typ. the value computed
[in]	delta	allowed max absolute difference

Returns: 0 if OK, 1 on error Note: a failure in comparison is not an error

Definition at line 270 of file regutils.c.

References L_RegParams::fp, L_RegParams::index, L_RegParams::success, and L_RegParams::testname.

◆ regTestGenLocalFilename()

char * regTestGenLocalFilename	(	L_REGPARAMS *	rp,
		l_int32	index,
		l_int32	format )

regTestGenLocalFilename()

Parameters

[in]	rp	regtest parameters
[in]	index	use -1 for current index
[in]	format	of image; e.g., IFF_PNG

Returns: filename if OK, or NULL on error

Notes:
     (1) This is used to get the name of a file in the regout
         subdirectory, that has been made and is used to test against
         the golden file.  You can either specify a particular index
         value, or with index == -1, this returns the most recently
         written file.  The latter case lets you read a pix from a
         file that has just been written with regTestWritePixAndCheck(),
         which is useful for testing formatted read/write functions.

Definition at line 805 of file regutils.c.

References L_RegParams::index, and L_RegParams::testname.

◆ regTestSetup()

l_ok regTestSetup	(	l_int32	argc,
		char **	argv,
		L_REGPARAMS **	prp )

regTestSetup()

Parameters

[in]	argc	from invocation; can be either 1 or 2
[in]	argv	to regtest: argv[1] is one of these: "generate", "compare", "display"
[out]	prp	all regression params

Returns: 0 if OK, 1 on error

Notes:
     (1) Call this function with the args to the reg test.  The first arg
         is the name of the reg test.  There are three cases:
         Case 1:
             There is either only one arg, or the second arg is "compare".
             This is the mode in which you run a regression test
             (or a set of them), looking for failures and logging
             the results to a file.  The output, which includes
             logging of all reg test failures plus a SUCCESS or
             FAILURE summary for each test, is appended to the file
             "/tmp/lept/reg_results.txt.  For this case, as in Case 2,
             the display field in rp is set to FALSE, preventing
             image display.
         Case 2:
             The second arg is "generate".  This will cause
             generation of new golden files for the reg test.
             The results of the reg test are not recorded, and
             the display field in rp is set to FALSE.
         Case 3:
             The second arg is "display".  The test will run and
             files will be written.  Comparisons with golden files
             will not be carried out, so the only notion of success
             or failure is with tests that do not involve golden files.
             The display field in rp is TRUE, and this is used by
             pixDisplayWithTitle().
     (2) See regutils.h for examples of usage.

Definition at line 123 of file regutils.c.

References L_RegParams::display, L_RegParams::fp, getRootNameFromArgv0(), L_RegParams::index, L_RegParams::mode, L_RegParams::success, L_RegParams::tempfile, L_RegParams::testname, and L_RegParams::tstart.

◆ regTestWriteDataAndCheck()

l_ok regTestWriteDataAndCheck	(	L_REGPARAMS *	rp,
		void *	data,
		size_t	nbytes,
		const char *	ext )

regTestWriteDataAndCheck()

Parameters

[in]	rp	regtest parameters
[in]	data	to be written
[in]	nbytes	of data to be written
[in]	ext	filename extension (e.g.: "ba", "pta")

Returns: 0 if OK, 1 on error Note: a failure in comparison is not an error

Notes:
     (1) This function makes it easy to write data in a numbered
         sequence of files, and either to:
            (a) write the golden file ("generate" arg to regression test)
            (b) make a local file and "compare" with the golden file
            (c) make a local file and "display" the results
     (2) The canonical format of the local filename is:
           /tmp/lept/regout/[root of main name].[count].[ext]
         e.g., for the first boxaa in quadtree_reg,
           /tmp/lept/regout/quadtree.0.baa
         The golden file name mirrors this in the usual way.
     (3) The data can be anything.  It is most useful for serialized
         output of data, such as boxa, pta, etc.
     (4) The file extension is arbitrary.  It is included simply
         to make the content type obvious when examining written files.
     (5) The check is done between the written files, which requires
         the files to be identical.

Definition at line 756 of file regutils.c.

References L_RegParams::index, regTestCheckFile(), L_RegParams::success, and L_RegParams::testname.

◆ regTestWritePixAndCheck()

l_ok regTestWritePixAndCheck	(	L_REGPARAMS *	rp,
		PIX *	pix,
		l_int32	format )

regTestWritePixAndCheck()

Parameters

[in]	rp	regtest parameters
[in]	pix	to be written
[in]	format	of output pix

Returns: 0 if OK, 1 on error Note: a failure in comparison is not an error

Notes:
     (1) This function makes it easy to write the pix in a numbered
         sequence of files, and either to:
            (a) write the golden file ("generate" arg to regression test)
            (b) make a local file and "compare" with the golden file
            (c) make a local file and "display" the results
     (2) The canonical format of the local filename is:
           /tmp/lept/regout/[root of main name].[count].[format extension]
         e.g., for scale_reg,
           /tmp/lept/regout/scale.0.png
         The golden file name mirrors this in the usual way.
     (3) The check is done between the written files, which requires
         the files to be identical. The exception is for GIF, which
         only requires that all pixels in the decoded pix are identical.

Definition at line 687 of file regutils.c.

References L_RegParams::index, regTestCheckFile(), L_RegParams::success, and L_RegParams::testname.

Variable Documentation

◆ ImageFileFormatExtensions

const char* ImageFileFormatExtensions[]

extern

Definition at line 124 of file writefile.c.

◆ NumImageFileFormatExtensions

l_int32 NumImageFileFormatExtensions

extern

Definition at line 123 of file writefile.c.

Functions

Variables

Detailed Description

Function Documentation

◆ getRootNameFromArgv0()

◆ regTestCheckFile()

◆ regTestCleanup()

◆ regTestCompareFiles()

◆ regTestComparePix()

◆ regTestCompareSimilarPix()

◆ regTestCompareStrings()

◆ regTestCompareValues()

◆ regTestGenLocalFilename()

◆ regTestSetup()

◆ regTestWriteDataAndCheck()

◆ regTestWritePixAndCheck()

Variable Documentation

◆ ImageFileFormatExtensions

◆ NumImageFileFormatExtensions