************************************************************************************************** * * Source structure of libQuality * ************************************************************************************************** The text below uses the following terminology: Component = piece of software that is in some way encapsulated. Menu-Module = Component that registers Menu Parameters in the user interface. Non-Menu Component = Component that does NOT register Menu Parameters in the user interface (and that gets its parameter values via other routes, e.g. via function arguments). ================================================================================================== Overview ================================================================================================== Dependency diagram. Each block outlined with SOLID LINES represents a Component implemented as a separate .c file plus associated .h file. The diagram shows also the internal structure of the sourcefile pair 'quality.c/.h'. This sourcefile pair defines five small classes, shown as blocks outlined with DOTTED LINES. These are the class 'QualityModul', which is the top-level GUI class for Grading as a whole, plus a separate class for each of the four four Extraction Channels. These five small classes (explained further in section "Main module" below) are all implemented inside the sourcefile pair quality.c/.h and not in separate .c and .h files; nonetheless these classes are by design clearly separate Components. Each block X (whether solid or dotted) uses only those other blocks that are drawn vertically below block X. The things within round brackets () are comments, not names of software components. +--------------------------------------------------------------------------------------------------------------------------------------------------+ | quality.c | | | | +..............................................................................................................................................+ | | : : | | : QualityModul : | | : : | | : +..........................+...................+.................................+..........................+ | | : : : : : : | | : (Preprocessing steps) : ExtrChEinbuchtungen : ExtrChFettanteil : ExtrChPrimaryEye : ExtrChBlutstellen : | | : : : : : : | | +..................................+..........................+...................+.................................+..........................+ | | | +-+--------------+-------------------+---------------------+----+-------------------+---------------------------------+---------------------+----+-+ | | | | | | | | | | combCont1.c | appRLEMaskMaker.c | appEinbFinder.c | B | appFettFinder.c | appPrEyeFinder.c | appBlutstFinder.c | B | | | | | | | | | | | | +---------------------+ +-------------------+---------------+-----------------+---------------------+ | | | | | | | | | | | | | | detectConcavities.c | | fettantAdapt.c | findXGrenze.c | prEyeAuxFuncs.c | octagonFilter.c | | | | | | | | | | | | | | | | | | | +---------------------+ | | | | | | | | | | | | | | | | | | | RunningMinimum256.c | | | | | | | | | | | | +--------------+-------------------+---------------------+----+-------------------+---------------+-----------------+---------------------+----+ | | | General-purpose modules | | [outval.h, historicMedian.c, konturAdapter.h, vertRLE.c, | | dumpFourCurves.c, dbgPrinter.h, imgDump.c, fwriteImg.c, freadImg.c] | | | +----------------------------------------------------------------------------------------------------------------------------------------------+ B = bewertung.c ================================================================================================== Main module: ================================================================================================== quality.h quality.c Menu-Module. (= class QualityModul) The internal structure of quality.h/.c is shown schematically in the dependency diagram above (see the dotted blocks inside of the solid-outlined block on top). quality.h/.c first defines four classes, one for each of the four Extraction Channels (see redmine: projects/webersoft/wiki/GradingTerminologyExtrVerarbKan), namely: class ExtrChEinbuchtungen Purpose: Extraction Channel for Einbuchtungen Contains: Erkennungsteil = instance of class EinbFinder (from appEinbFinder.h) Bewertungsteil = instance of class BewertungsModul (from bewertung.h) class ExtrChFettanteil Purpose: Extraction Channel for Fettanteil Contains: Erkennungsteil = instance of class FettFinder (from appFettFinder.h) [Note: The trivial Bewertungsteil, which has no menu parameters, is coded out in ExtrChFettanteil::execErkennungAndBewertung()] class ExtrChPrimaryEye Purpose: Extraction Channel for Primary Eye Contains: Erkennungsteil = instance of class PrEyeFinder (from appPrEyeFinder.h) [Note: The trivial Bewertungsteil, which has no menu parameters, is coded out in ExtrChPrimaryEye::execErkennungAndBewertung()] class ExtrChBlutstellen Purpose: Extraction Channel for Blutstellen Contains: Erkennungsteil = instance of class BlutstFinder (from appBlutstFinder.h) Bewertungsteil = instance of class BewertungsModul (from bewertung.h) Each "Extraction Channel" class is a container for the Erkennungsteil and the Bewertungsteil in that Extraction Channel, and is also a Menu-Module containing a menu page with the Erkennungsteil and Bewertungsteil parameters as sub-menus. Each "Extraction Channel" class implements a function 'execErkennungAndBewertung()' which executes first the Erkennungsteil and then the Bewertungsteil. Each "Extraction Channel" class is a separate, independent component, that knows nothing about any other Extraction Channel. The second and final part of part of quality.h/.c defines the class QualityModul, which is a Menu-Module for Grading as a whole. Purposes of class QualityModul: 1- Function "doIt()" calls the top-level (exported) functions of the Components that execute the successive *Grading processing steps*, namely: 1a) First it executes the preprocessing steps: 1a.1- First it calls the function 'combCont1()' from combCont1.h to combine the four input Taster-Curves to a closed contour. 1a.2- Then it calls RLEMaskMaker from appRLEMaskMaker.h to create the "RLE masks" (see redmine: projects/webersoft/wiki/Grading) used by the four Extraction Channels. 1b) Then it calls the function 'execErkennungAndBewertung()' of all four Extraction Channels, in order. 1c) Finally it runs a temporary (as long as not implemented by Weber) Entscheidungsteil, coded out inside quality.c but using Decision Thresholds (menu parameter values) from the Menu-Module 'entscheidungsteil.h/.c'. For software technical reasons (namely, to make it easier to print the Bewertungszahlen on the overlay even when any processing step fails and aborts), steps 1a and 1b are actually delegated to the private function 'QualityModul::executeAllGradingSteps()'. 2- Container for the preprocessing RLEMaskMaker instance(*) and for the four Extraction Channels, in the user interface. [(*) The other preprocessing step, combCont1(), from combCont1.h, has no menu parameters, and therefore doesn't appear in the menus.] 4- Defines access functions through which client code, after a call to QualityModul::doIt(), can read the Bewertungszahlen for all Extraction Channels. 3- Defines the class function 'QualityModul::testLib()', which calls the unit test functions 'testUnit()' of all Grading submodules (for those that have unit tests defined). Important: testLib() and all testUnit() are CLASS functions, i.e. do not depend on any menu parameter values. If compiled with DEVELOP defined, then the Grading top-level menu contains a button "Execute unit tests", which calls 'QualityModul::testLib()'. ================================================================================================== Grading preprocessing steps: ================================================================================================== Each of these components (consisting of a .c file and its .h file) is completely independent and knows nothing about any other component, except (and this is the only exception) that the function 'combCont1()' from combCont1.h is used by "libQuality/flodder.c". combCont1.h combCont1.c Non-Menu Component. Purpose: Function combCont1() = Combining of the 4 Taster-Curves to a closed contour. This is the only exported function from this Component. This operation does not use any parameters, hence no menu parameters. Called by: 1) quality.c. 2) "libAuswertung/flodder.c". Notes: The "cross dependency" between libQuality/flodder.c and combCont1.c should be only temporary, and should disappear when instead of the 4 taster curves, a closed contour is passed from the Optische Waage to Grading. Then the combCont1 Component should move from Grading (libQuality) to the Optische Waage. Note that the Grading software is already prepared for getting its input in the form of a closed contour (rather than 4 separate Taster Curves as at present): internally, Grading already constructs its masks (vertRLE) from a closed contour and not from the four separate Taster Curves. (At present, the closed contour used for this is, inside Grading, constructed from the 4 Taster-Curves passed to Grading.) appRLEMaskMaker.h appRLEMaskMaker.c Menu-Module. (= class RLEMaskMaker) High-level menu module for creation, from the 4 Taster-Curves, of the create Masks (for the interior of the contour) used by the Fettanteil recognition and by the Blutstellen recognition. Makes heavy use of the functionality implemented in vertRLE.c/.h. ================================================================================================== The *Erkennungsteile* for each of the Extraction Channels: ================================================================================================== These form four separate sets of source files, one separate set of sourcefiles for each of the four Erkennungsteile. The sources for one Erkennungsteil are independent of, and know nothing about, the other Erkennungsteile, and/or the grading preprocessing steps. * Einbuchtungen ~~~~~~~~~~~~~ appEinbFinder.h appEinbFinder.c Menu-Module. (= class EinbFinder) High-level menu module for the recognition of Einbuchtungen (concavities) in the contour. Internally uses fettantAdapt.h/.c to carry out the actual work. detectConcavities.h detectConcavities.c Non-Menu Component. Purpose: Detection of Einbuchtungen (concavities) in the contour, via Hafthuelle (Sticky Hull). Used only by appEinbFinder.c. Internal dependencies for the Fettanteil Erkennungsteil (a block uses the blocks vertically below it): +-----------------------------------------------+ | appEinbFinder.c | +-----------------------------------------------+ | detectConcavities.c | +-----------------------------------------------+ * Fettanteil ~~~~~~~~~~ appFettFinder.h appFettFinder.c Menu-Module. (= class FettFinder) High-level menu module for the Fettanteil recognition. Internally uses fettantAdapt.h/.c to carry out the actual work. Also implements the class function FettFinder::testUnit(). fettantAdapt.h fettantAdapt.c Non-Menu Component. Purpose: Fettanteil recognition inside contour, via adaptive thresholding. Used only by appFettFinder.c. Internal dependencies for the Fettanteil Erkennungsteil (a block uses the blocks vertically below it): +-----------------------------------------------+ | appFettFinder.c | +-----------------------------------------------+ | fettantAdapt.c | +-----------------------------------------------+ * Primary Eye ~~~~~~~~~~~ appPrEyeFinder.h appPrEyeFinder.c Menu-Module. (= class PrEyeFinder) High-level menu module for the Primary-Eye recognition. Contains: - PrEyeFinder::doIt() Executes the Primary-Eye recognition. - doAllFilterings() Only used by PrEyeFinder::doIt(). Implements the underlying Primary-Eye recognition, at its highest level. - class function FettFinder::testUnit() Unit test function, called by QualityModul::testLib(). findXGrenze.h findXGrenze.c Used only by appPrEyeFinder.c:doAllFilterings(). Detects vertical curve of connected edge pixels, where "edge" is defined as a left-to-right dark-to-bright transision; and finds the x-coordinate of the "heaviest" curve. Weighting according to: Length of the curve; Verticality (vs. Skew) of the curve; Depth of bright pixels to thr right ofthe curve; Weighting additionally with an x-dependent Gaussian bell curve. prEyeAuxFuncs.h prEyeAuxFuncs.c Used only by appPrEyeFinder.c:doAllFilterings(). Functions for extraction of subwindow from image; rotation; mirroring; etc. Internal dependencies for the Primary-Eye Erkennungsteil (a block uses the blocks vertically below it): +-------------------------------------------------------------------------+ | | | appPrEyeFinder.c : doIt() | | | +-------------------------------------------------------------------------+ | | | appPrEyeFinder.c : doAllFilterings() | | | +-----------------------------------+-------------------------------------+ | | | | findXGrenze.c | prEyeAuxFuncs.c | | | | +-----------------------------------+-------------------------------------+ * Blutstellen ~~~~~~~~~~~ appBlutstFinder.h appBlutstFinder.c Menu-Module. (= class BlutstFinder) High-level menu module for the Blutstellen recognition. Contains: - PrEyeFinder::doIt() Executes the Blutstellen recognition. - Running of local Tests (as yet without automatic checking of test outputs, and as yet not executed from QualityModul::testLib()). octagonFilter.h octagonFilter.c Used only by 'appBlutstFinder.c'. Non-menu component, implements the Blutstellen recognition, via binarizing octagon filtering, followed by connected-components finding. RunningMinimum256.h RunningMinimum256.c Non-menu component. General-purpose class 'RunningMinimum256', implementing a fast running minimum for U8 pixel grayvalues. Used in 'octagonFilter.c'. [NB: Please Note the difference between RunningMinimum256.h/c and RunningMedian256.h/c] Internal dependencies for the Blutstellen Erkennungsteil (a block uses the blocks vertically below it): +-----------------------------------------------+ | appBlutstFinder.c | +-----------------------------------------------+ | octagonFilter.c | +-----------------------------------------------+ | RunningMinimum256.c | +-----------------------------------------------+ ================================================================================================== Bewertungsteil: ================================================================================================== bewertung.h bewertung.c Menu-Module. General-purpose Bewertungsteil (= class BewertungsModul). At this moment only used by QualityModul (= quality.h/.c). ================================================================================================== Auxiliary Components, part one -- Payload functionality ================================================================================================== outval.h Non-Menu Component. Auxiliary class 'OutVal', for conversion of quantities for output via CAN. Purpose: Mapping of real number to unsigned 8- or 32-bit number. Objects of type 'OutVal' are used internally inside the Extraction Channel classes inside quality.c, to contain the Bewertungszahlen. Objects of type 'OutVal' are (currently) used nowhere else. The class 'OutVal' further defines a public enum OutVal::state_t, for the state of a Bewertungszahl (EMPTY, UNREACHED, FAILED, VALID). This enum is exported, from the whole quality.h module (via #include "outval.h" in quality.h), namely these enum values are used the return values by the getter functions through which client code can read the Bewertungszahlen. (Client code can optionally use these return values when it needs the state information.) historicMedian.h historicMedian.c Non-Menu Component. Purpose: Historic Median memory and -updating. Used only by the Extraction Channel for Primary Eye, inside 'quality.c'. konturAdapter.h Non-Menu Component. Interface 'IKonturAdapter' + implementations. Purpose: Unified read-only access to a closed contour or polygon (with vertices ordered, starting at any vertex). So that code that processes a contour/polygon can read from any type of contour/polygon (as long as it is a datatype based on tPunkt). Used by appRLEMaskMaker.c, appFettFinder.c, vertRLE.c. vertRLE.h vertRLE.c Non-Menu Component. Purpose: Definition of data structure for one vertical RLE mask; and operations on vertical RLE masks. Used above all in appRLEMaskMaker.c, but also used in most or all of the Grading processing (since all grading steps operate within a contour = within the vertical RLE mask). ================================================================================================== Auxiliary Components, part two -- Logging and debug/test functionality ================================================================================================== dumpFourCurves.h dumpFourCurves.c Non-Menu Component. Purpose: Dumps the four input Taster Curves to the telnet log, for debug. Only called by 'quality.c'. dbgPrinter.h Non-Menu Component. Implements class 'DbgPrinter'. Purpose: to make nicely formatted telnet log printing from inside a (large) function easier. imgDump.h imgDump.c Non-Menu Component. Purpose: Dump the contents of a wtImage on the telnet log, for test/debug. fwriteImg.h fwriteImg.c Non-Menu Component. Purpose: Write the contents of a wtImage as a PGM P2 file to "pc:", for test/debug. freadImg.h freadImg.c Non-Menu Component. Purpose: Read PGM P2 file, or a BMP file, from "pc:" into a wtImage, for test/debug. ================================================================================================== NO LONGER USED ================================================================================================== The following components were implemented (and tested) for the Primary-Eye recognition, and were used in a previous version of the Primary-Eye recognition, but are now NO LONGER USED. These components are not (yet) removed from the Weberprojekte source tree. (Maybe another application may at some future time may find a use for these components.) libQuality/RunningMedian256.h libQuality/RunningMedian256.c Fast Running Median implementation, for items of type U8 (pixel grayvalues). [NB: Please Note the difference between RunningMinimum256.h/c and RunningMedian256.h/c] libFast/Hist256.h libFast/Hist256.c Histogram implementation for items of type U8 (pixel grayvalues), with fast access to smallest and biggest items. Used by 'RunningMedian256.c'. Put in libFast because the functions it uses from 'bitOpsU16.c' are inlined; therefore because 'bitOpsU16.c' has to be compiled with special compiler flags, 'Hist256.c' has to be compiled with these same special compiler flags. libFast/bitOpsU16.h libFast/bitOpsU16.c Bit operations used in 'Hist256.c'. Put in libFast because the TI "intrinsics" _lmbd() and _bitr() have to be compiled with special compiler flags.