Leptonica  1.83.1
Image processing and image analysis suite
selgen.c File Reference
#include "allheaders.h"

Go to the source code of this file.

Macros

#define DEBUG_DISPLAY_HM_SEL   0
 

Functions

SELpixGenerateSelWithRuns (PIX *pixs, l_int32 nhlines, l_int32 nvlines, l_int32 distance, l_int32 minlength, l_int32 toppix, l_int32 botpix, l_int32 leftpix, l_int32 rightpix, PIX **ppixe)
 
SELpixGenerateSelRandom (PIX *pixs, l_float32 hitfract, l_float32 missfract, l_int32 distance, l_int32 toppix, l_int32 botpix, l_int32 leftpix, l_int32 rightpix, PIX **ppixe)
 
SELpixGenerateSelBoundary (PIX *pixs, l_int32 hitdist, l_int32 missdist, l_int32 hitskip, l_int32 missskip, l_int32 topflag, l_int32 botflag, l_int32 leftflag, l_int32 rightflag, PIX **ppixe)
 
NUMApixGetRunCentersOnLine (PIX *pixs, l_int32 x, l_int32 y, l_int32 minlength)
 
NUMApixGetRunsOnLine (PIX *pixs, l_int32 x1, l_int32 y1, l_int32 x2, l_int32 y2)
 
PTApixSubsampleBoundaryPixels (PIX *pixs, l_int32 skip)
 
l_int32 adjacentOnPixelInRaster (PIX *pixs, l_int32 x, l_int32 y, l_int32 *pxa, l_int32 *pya)
 
PIXpixDisplayHitMissSel (PIX *pixs, SEL *sel, l_int32 scalefactor, l_uint32 hitcolor, l_uint32 misscolor)
 

Variables

static const l_int32 DefaultDistanceToBoundary = 1
 
static const l_int32 MaxDistanceToBoundary = 4
 
static const l_int32 DefaultMinRunlength = 3
 
static const l_int32 DefaultSelScalefactor = 7
 
static const l_int32 MaxSelScalefactor = 31
 

Detailed Description


     This file contains functions that generate hit-miss Sels
     for doing a loose match to a small bitmap.  The hit-miss
     Sel is made from a given bitmap.  Several "knobs"
     are available to control the looseness of the match.
     In general, a tight match will have fewer false positives
     (bad matches) but more false negatives (missed patterns).
     The values to be used depend on the quality and variation
     of the image in which the pattern is to be searched,
     and the relative penalties of false positives and
     false negatives.  Default values for the three knobs --
     minimum distance to boundary pixels, number of extra pixels
     added to selected sides, and minimum acceptable runlength
     in eroded version -- are provided.

     The generated hit-miss Sels can always be used in the
     rasterop implementation of binary morphology (in morph.h).
     If they are small enough (not more than 31 pixels extending
     in any direction from the Sel origin), they can also be used
     to auto-generate dwa code (fmorphauto.c).


     Generate a subsampled structuring element
           SEL     *pixGenerateSelWithRuns()
           SEL     *pixGenerateSelRandom()
           SEL     *pixGenerateSelBoundary()

     Accumulate data on runs along lines
           NUMA    *pixGetRunCentersOnLine()
           NUMA    *pixGetRunsOnLine()

     Subsample boundary pixels in relatively ordered way
           PTA     *pixSubsampleBoundaryPixels()
           PTA     *adjacentOnPixelInRaster()

     Display generated sel with originating image
           PIX     *pixDisplayHitMissSel()

Definition in file selgen.c.

Function Documentation

◆ adjacentOnPixelInRaster()

l_int32 adjacentOnPixelInRaster ( PIX pixs,
l_int32  x,
l_int32  y,
l_int32 *  pxa,
l_int32 *  pya 
)

adjacentOnPixelInRaster()

Parameters
[in]pixs1 bpp
[in]x,ycurrent pixel
[out]pxa,pyaadjacent ON pixel, found by simple CCW search
Returns
1 if a pixel is found; 0 otherwise or on error
Notes:
     (1) Search is in 4-connected directions first; then on diagonals.
         This allows traversal along a 4-connected boundary.

Definition at line 860 of file selgen.c.

◆ pixDisplayHitMissSel()

PIX* pixDisplayHitMissSel ( PIX pixs,
SEL sel,
l_int32  scalefactor,
l_uint32  hitcolor,
l_uint32  misscolor 
)

pixDisplayHitMissSel()

Parameters
[in]pixs1 bpp
[in]selhit-miss in general
[in]scalefactoran integer >= 1; use 0 for default
[in]hitcolorRGB0 color for center of hit pixels
[in]misscolorRGB0 color for center of miss pixels
Returns
pixd RGB showing both pixs and sel, or NULL on error
Notes:
   (1) We don't allow scalefactor to be larger than MaxSelScalefactor
   (2) The colors are conveniently given as 4 bytes in hex format,
       such as 0xff008800.  The least significant byte is ignored.

Definition at line 916 of file selgen.c.

◆ pixGenerateSelBoundary()

SEL* pixGenerateSelBoundary ( PIX pixs,
l_int32  hitdist,
l_int32  missdist,
l_int32  hitskip,
l_int32  missskip,
l_int32  topflag,
l_int32  botflag,
l_int32  leftflag,
l_int32  rightflag,
PIX **  ppixe 
)

pixGenerateSelBoundary()

Parameters
[in]pixs1 bpp, typically small, to be used as a pattern
[in]hitdistmin distance from fg boundary pixel
[in]missdistmin distance from bg boundary pixel
[in]hitskipnumber of boundary pixels skipped between hits
[in]missskipnumber of boundary pixels skipped between misses
[in]topflagflag for extra pixels of bg added above
[in]botflagflag for extra pixels of bg added below
[in]leftflagflag for extra pixels of bg added to left
[in]rightflagflag for extra pixels of bg added to right
[out]ppixe[optional] input pix expanded by extra pixels
Returns
sel hit-miss for input pattern, or NULL on error
Notes:
   (1) All fg elements selected are exactly hitdist pixels away from
       the nearest fg boundary pixel, and ditto for bg elements.
       Valid inputs of hitdist and missdist are 0, 1, 2, 3 and 4.
       For example, a hitdist of 0 puts the hits at the fg boundary.
       Usually, the distances should be > 0 avoid the effect of
       noise at the boundary.
   (2) Set hitskip < 0 if no hits are to be used.  Ditto for missskip.
       If both hitskip and missskip are < 0, the sel would be empty,
       and NULL is returned.
   (3) The 4 flags determine whether the sel is increased on that side
       to allow bg misses to be placed all along that boundary.
       The increase in sel size on that side is the minimum necessary
       to allow the misses to be placed at mindist.  For text characters,
       the topflag and botflag are typically set to 1, and the leftflag
       and rightflag to 0.
   (4) The input pix, as extended by the extra pixels on selected sides,
       can optionally be returned.  For debugging, call
       pixDisplayHitMissSel() to visualize the hit-miss sel superimposed
       on the generating bitmap.
   (5) This is probably the best of the three sel generators, in the
       sense that you have the most flexibility with the smallest number
       of hits and misses.

Definition at line 487 of file selgen.c.

◆ pixGenerateSelRandom()

SEL* pixGenerateSelRandom ( PIX pixs,
l_float32  hitfract,
l_float32  missfract,
l_int32  distance,
l_int32  toppix,
l_int32  botpix,
l_int32  leftpix,
l_int32  rightpix,
PIX **  ppixe 
)

pixGenerateSelRandom()

Parameters
[in]pixs1 bpp, typically small, to be used as a pattern
[in]hitfractfraction of allowable fg pixels that are hits
[in]missfractfraction of allowable bg pixels that are misses
[in]distancemin distance from boundary pixel; use 0 for default
[in]toppixnumber of extra pixels of bg added above
[in]botpixnumber of extra pixels of bg added below
[in]leftpixnumber of extra pixels of bg added to left
[in]rightpixnumber of extra pixels of bg added to right
[out]ppixe[optional] input pix expanded by extra pixels
Returns
sel hit-miss for input pattern, or NULL on error
Notes:
   (1) Either of hitfract and missfract can be zero.  If both are zero,
       the sel would be empty, and NULL is returned.
   (2) No elements are selected that are less than 'distance' pixels away
       from a boundary pixel of the same color.  This makes the
       match much more robust to edge noise.  Valid inputs of
       'distance' are 0, 1, 2, 3 and 4.  If distance is either 0 or
       greater than 4, we reset it to the default value.
   (3) The 4 numbers for adding rectangles of pixels outside the fg
       can be use if the pattern is expected to be surrounded by bg
       (white) pixels.  On the other hand, if the pattern may be near
       other fg (black) components on some sides, use 0 for those sides.
   (4) The input pix, as extended by the extra pixels on selected sides,
       can optionally be returned.  For debugging, call
       pixDisplayHitMissSel() to visualize the hit-miss sel superimposed
       on the generating bitmap.

Definition at line 336 of file selgen.c.

◆ pixGenerateSelWithRuns()

SEL* pixGenerateSelWithRuns ( PIX pixs,
l_int32  nhlines,
l_int32  nvlines,
l_int32  distance,
l_int32  minlength,
l_int32  toppix,
l_int32  botpix,
l_int32  leftpix,
l_int32  rightpix,
PIX **  ppixe 
)

pixGenerateSelWithRuns()

Parameters
[in]pixs1 bpp, typically small, to be used as a pattern
[in]nhlinesnumber of hor lines along which elements are found
[in]nvlinesnumber of vert lines along which elements are found
[in]distancemin distance from boundary pixel; use 0 for default
[in]minlengthmin runlength to set hit or miss; use 0 for default
[in]toppixnumber of extra pixels of bg added above
[in]botpixnumber of extra pixels of bg added below
[in]leftpixnumber of extra pixels of bg added to left
[in]rightpixnumber of extra pixels of bg added to right
[out]ppixe[optional] input pix expanded by extra pixels
Returns
sel hit-miss for input pattern, or NULL on error
Notes:
   (1) The horizontal and vertical lines along which elements are
       selected are roughly equally spaced.  The actual locations of
       the hits and misses are the centers of respective run-lengths.
   (2) No elements are selected that are less than 'distance' pixels away
       from a boundary pixel of the same color.  This makes the
       match much more robust to edge noise.  Valid inputs of
       'distance' are 0, 1, 2, 3 and 4.  If distance is either 0 or
       greater than 4, we reset it to the default value.
   (3) The 4 numbers for adding rectangles of pixels outside the fg
       can be use if the pattern is expected to be surrounded by bg
       (white) pixels.  On the other hand, if the pattern may be near
       other fg (black) components on some sides, use 0 for those sides.
   (4) The pixels added to a side allow you to have miss elements there.
       There is a constraint between distance, minlength, and
       the added pixels for this to work.  We illustrate using the
       default values.  If you add 5 pixels to the top, and use a
       distance of 1, then you end up with a vertical run of at least
       4 bg pixels along the top edge of the image.  If you use a
       minimum runlength of 3, each vertical line will always find
       a miss near the center of its run.  However, if you use a
       minimum runlength of 5, you will not get a miss on every vertical
       line.  As another example, if you have 7 added pixels and a
       distance of 2, you can use a runlength up to 5 to guarantee
       that the miss element is recorded.  We give a warning if the
       constraint does not guarantee a miss element outside the
       image proper.
   (5) The input pix, as extended by the extra pixels on selected sides,
       can optionally be returned.  For debugging, call
       pixDisplayHitMissSel() to visualize the hit-miss sel superimposed
       on the generating bitmap.

Definition at line 148 of file selgen.c.

◆ pixGetRunCentersOnLine()

NUMA* pixGetRunCentersOnLine ( PIX pixs,
l_int32  x,
l_int32  y,
l_int32  minlength 
)

pixGetRunCentersOnLine()

Parameters
[in]pixs1 bpp
[in]x,yset one of these to -1; see notes
[in]minlengthminimum length of acceptable run
Returns
numa of fg runs, or NULL on error
Notes:
     (1) Action: this function computes the fg (black) and bg (white)
         pixel runlengths along the specified horizontal or vertical line,
         and returns a Numa of the "center" pixels of each fg run
         whose length equals or exceeds the minimum length.
     (2) This only works on horizontal and vertical lines.
     (3) For horizontal runs, set x = -1 and y to the value
         for all points along the raster line.  For vertical runs,
         set y = -1 and x to the value for all points along the
         pixel column.
     (4) For horizontal runs, the points in the Numa are the x
         values in the center of fg runs that are of length at
         least 'minlength'.  For vertical runs, the points in the
         Numa are the y values in the center of fg runs, again
         of length 'minlength' or greater.
     (5) If there are no fg runs along the line that satisfy the
         minlength constraint, the returned Numa is empty.  This
         is not an error.

Definition at line 632 of file selgen.c.

◆ pixGetRunsOnLine()

NUMA* pixGetRunsOnLine ( PIX pixs,
l_int32  x1,
l_int32  y1,
l_int32  x2,
l_int32  y2 
)

pixGetRunsOnLine()

Parameters
[in]pixs1 bpp
[in]x1,y1,x2,y2
Returns
numa, or NULL on error
Notes:
     (1) Action: this function uses the bresenham algorithm to compute
         the pixels along the specified line.  It returns a Numa of the
         runlengths of the fg (black) and bg (white) runs, always
         starting with a white run.
     (2) If the first pixel on the line is black, the length of the
         first returned run (which is white) is 0.

Definition at line 702 of file selgen.c.

◆ pixSubsampleBoundaryPixels()

PTA* pixSubsampleBoundaryPixels ( PIX pixs,
l_int32  skip 
)

pixSubsampleBoundaryPixels()

Parameters
[in]pixs1 bpp, with only boundary pixels in fg
[in]skipnumber to skip between samples as you traverse boundary
Returns
pta, or NULL on error
Notes:
     (1) If skip = 0, we take all the fg pixels.
     (2) We try to traverse the boundaries in a regular way.
         Some pixels may be missed, and these are then subsampled
         randomly with a fraction determined by 'skip'.
     (3) The most natural approach is to use a depth first (stack-based)
         method to find the fg pixels.  However, the pixel runs are
         4-connected and there are relatively few branches.  So
         instead of doing a proper depth-first search, we get nearly
         the same result using two nested while loops: the outer
         one continues a raster-based search for the next fg pixel,
         and the inner one does a reasonable job running along
         each 4-connected coutour.

Definition at line 795 of file selgen.c.