/ocr/ocrservice/jni/hydrogen/include/leptonica/regutils.h

  1/*====================================================================*
  2 -  Copyright (C) 2001 Leptonica.  All rights reserved.
  3 -  This software is distributed in the hope that it will be
  4 -  useful, but with NO WARRANTY OF ANY KIND.
  5 -  No author or distributor accepts responsibility to anyone for the
  6 -  consequences of using this software, or for whether it serves any
  7 -  particular purpose or works at all, unless he or she says so in
  8 -  writing.  Everyone is granted permission to copy, modify and
  9 -  redistribute this source code, for commercial or non-commercial
 10 -  purposes, with the following restrictions: (1) the origin of this
 11 -  source code must not be misrepresented; (2) modified versions must
 12 -  be plainly marked as such; and (3) this notice may not be removed
 13 -  or altered from any source or modified source distribution.
 14 *====================================================================*/
 15
 16#ifndef  LEPTONICA_REGUTILS_H
 17#define  LEPTONICA_REGUTILS_H
 18
 19/*
 20 *   regutils.h
 21 *
 22 *   Contains this regression test parameter packaging struct
 23 *       struct L_RegParams
 24 *
 25 *
 26 *   The regression test utility allows you to write regression tests
 27 *   that compare results with existing "golden files".
 28 *
 29 *   Such regression tests can be called in three ways.
 30 *   For example, for distance_reg:
 31 *
 32 *       Case 1: distance_reg generate
 33 *           This generates golden files in /tmp for the reg test.
 34 *
 35 *       Case 2: distance_reg outfile.txt
 36 *           This runs the test against the set of golden files.  It
 37 *           appends to 'outfile.txt' either "SUCCESS" or "FAILURE",
 38 *           as well as the details of any parts of the test that failed.
 39 *
 40 *       Case 3: distance_reg
 41 *           This runs the test against the set of golden files.  The
 42 *           minimal output, which in case 2 went to a file, is
 43 *           instead sent to stderr.  In addition, this displays
 44 *           images and plots that are specified in the test under
 45 *           control of the @display variable.  The @display is
 46 *           only enabled when the regression test is called without
 47 *           any arguments (case 3).
 48 *
 49 *   Regression tests follow the pattern given below.  In an actual
 50 *   case, comparisons of pix and of files can occur in any order.
 51 *   We give a specific order here for clarity.
 52 *
 53 *       l_int32       success, display, count;
 54 *       FILE         *fp;  // stream only opened for case 2
 55 *       L_REGPARAMS  *rp;  // needed for either convenient argument
 56 *                          // passthrough to subroutines or for
 57 *                          // automated "write and check"
 58 *
 59 *       // Setup variables; optionally open stream
 60 *       if (regTestSetup(argc, argv, &fp, &display, &success, &rp))
 61 *           return 1;
 62 *
 63 *       // Test pairs of generated pix for identity.  Here we label
 64 *       // the count on the golden files (0 and 1) explicitly.
 65 *       regTestComparePix(fp, argv, pix1, pix2, 0, &success);
 66 *       regTestComparePix(fp, argv, pix1, pix2, 1, &success);
 67 *
 68 *       // Test pairs of generated pix for similarity.  These
 69 *       // generate or test against golden files 2 and 3.
 70 *       regTestCompareSimilarPix(fp, argv, pix1, pix2, 15, 0.001, 2,
 71 *                                &success, 0);
 72 *       regTestCompareSimilarPix(fp, argv, pix1, pix2, 15, 0.0005, 3,
 73 *                                &success, 0);
 74 *
 75 *       // Generation of <newfile*> outputs and testing for identity
 76 *       // These files can be anything, of course.
 77 *       regTestCheckFile(fp, argv, <newfile0>, 4, &success);
 78 *       regTestCheckFile(fp, argv, <newfile1>, 5, &success);
 79 *
 80 *       // Test pairs of output golden files for identity.  Here we
 81 *       // are comparing golden files 4 and 5.
 82 *       regTestCompareFiles(fp, argv, 4, 5, &success);
 83 *
 84 *       // "Write and check".  This writes a pix using a canonical
 85 *       // formulation for the local filename and either (a) generates a
 86 *       // golden file if requested or (b) tests the local file
 87 *       // against a golden file.  Here we are generating or testing
 88 *       // golden files 6 and 7, which are pix that have been
 89 *       // compressed with png and jpeg, respectively.  Each time that
 90 *       // regTestWritePixAndCheck() is called, the count is increased
 91 *       // by 1 and embedded in the local filename (and, if generating,
 92 *       // in the golden filename as well).
 93 *       count = 6;  // initialize it
 94 *       regTestWritePixAndCheck(pix1, IFF_PNG, &count, rp);
 95 *       regTestWritePixAndCheck(pix2, IFF_JFIF_JPEG, &count, rp);
 96 *
 97 *       // Display when reg test called with only one argument
 98 *       pixDisplayWithTitle(pix1, 100, 100, NULL, display);
 99 *
100 *       // Clean up and output result
101 *       regTestCleanup(argc, argv, fp, success, rp);
102 *
103 *  Note that the optional returned regparams (defined below) can be
104 *  used to pass the parameters cleanly through to subroutines; e.g.,
105 *
106 *        TestAll(Pix *pixs, L_RegParams *rp) {
107 *            ...
108 *            regTestCheckFile(rp->fp, rp->argv, fname, n, &rp->success);
109 *            ...
110 *        }
111 * 
112 */
113
114#include <stdio.h>
115
116/*-------------------------------------------------------------------------*
117 *                     Regression test parameter packer                    *
118 *-------------------------------------------------------------------------*/
119struct L_RegParams
120{
121    FILE          *fp;
122    char         **argv;
123    l_int32        success;
124    l_int32        display;
125};
126typedef struct L_RegParams  L_REGPARAMS;
127
128
129#endif  /* LEPTONICA_REGUTILS_H */
130