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

Go to the source code of this file.

Macros

#define SWAP(x, y)   {temp = (x); (x) = (y); (y) = temp;}
 

Functions

PIXpixExtractBoundary (PIX *pixs, l_int32 type)
 
PIXpixMorphSequenceMasked (PIX *pixs, PIX *pixm, const char *sequence, l_int32 dispsep)
 
PIXpixMorphSequenceByComponent (PIX *pixs, const char *sequence, l_int32 connectivity, l_int32 minw, l_int32 minh, BOXA **pboxa)
 
PIXApixaMorphSequenceByComponent (PIXA *pixas, const char *sequence, l_int32 minw, l_int32 minh)
 
PIXpixMorphSequenceByRegion (PIX *pixs, PIX *pixm, const char *sequence, l_int32 connectivity, l_int32 minw, l_int32 minh, BOXA **pboxa)
 
PIXApixaMorphSequenceByRegion (PIX *pixs, PIXA *pixam, const char *sequence, l_int32 minw, l_int32 minh)
 
PIXpixUnionOfMorphOps (PIX *pixs, SELA *sela, l_int32 type)
 
PIXpixIntersectionOfMorphOps (PIX *pixs, SELA *sela, l_int32 type)
 
PIXpixSelectiveConnCompFill (PIX *pixs, l_int32 connectivity, l_int32 minw, l_int32 minh)
 
l_ok pixRemoveMatchedPattern (PIX *pixs, PIX *pixp, PIX *pixe, l_int32 x0, l_int32 y0, l_int32 dsize)
 
PIXpixDisplayMatchedPattern (PIX *pixs, PIX *pixp, PIX *pixe, l_int32 x0, l_int32 y0, l_uint32 color, l_float32 scale, l_int32 nlevels)
 
PIXApixaExtendByMorph (PIXA *pixas, l_int32 type, l_int32 niters, SEL *sel, l_int32 include)
 
PIXApixaExtendByScaling (PIXA *pixas, NUMA *nasc, l_int32 type, l_int32 include)
 
PIXpixSeedfillMorph (PIX *pixs, PIX *pixm, l_int32 maxiters, l_int32 connectivity)
 
NUMApixRunHistogramMorph (PIX *pixs, l_int32 runtype, l_int32 direction, l_int32 maxsize)
 
PIXpixTophat (PIX *pixs, l_int32 hsize, l_int32 vsize, l_int32 type)
 
PIXpixHDome (PIX *pixs, l_int32 height, l_int32 connectivity)
 
PIXpixFastTophat (PIX *pixs, l_int32 xsize, l_int32 ysize, l_int32 type)
 
PIXpixMorphGradient (PIX *pixs, l_int32 hsize, l_int32 vsize, l_int32 smoothing)
 
PTApixaCentroids (PIXA *pixa)
 
l_ok pixCentroid (PIX *pix, l_int32 *centtab, l_int32 *sumtab, l_float32 *pxave, l_float32 *pyave)
 

Detailed Description


     These are some useful and/or interesting composite
     image processing operations, of the type that are often
     useful in applications.  Most are morphological in
     nature.

     Extraction of boundary pixels
           PIX       *pixExtractBoundary()

     Selective morph sequence operation under mask
           PIX       *pixMorphSequenceMasked()

     Selective morph sequence operation on each component
           PIX       *pixMorphSequenceByComponent()
           PIXA      *pixaMorphSequenceByComponent()

     Selective morph sequence operation on each region
           PIX       *pixMorphSequenceByRegion()
           PIXA      *pixaMorphSequenceByRegion()

     Union and intersection of parallel composite operations
           PIX       *pixUnionOfMorphOps()
           PIX       *pixIntersectionOfMorphOps()

     Selective connected component filling
           PIX       *pixSelectiveConnCompFill()

     Removal of matched patterns
           PIX       *pixRemoveMatchedPattern()

     Display of matched patterns
           PIX       *pixDisplayMatchedPattern()

     Extension of pixa by iterative erosion or dilation (and by scaling)
           PIXA      *pixaExtendByMorph()
           PIXA      *pixaExtendByScaling()

     Iterative morphological seed filling (don't use for real work)
           PIX       *pixSeedfillMorph()

     Granulometry on binary images
           NUMA      *pixRunHistogramMorph()

     Composite operations on grayscale images
           PIX       *pixTophat()
           PIX       *pixHDome()
           PIX       *pixFastTophat()
           PIX       *pixMorphGradient()

     Centroid of component
           PTA       *pixaCentroids()
           l_int32    pixCentroid()

Definition in file morphapp.c.

Function Documentation

◆ pixaCentroids()

PTA* pixaCentroids ( PIXA pixa)

pixaCentroids()

Parameters
[in]pixaof components; 1 or 8 bpp
Returns
pta of centroids relative to the UL corner of each pix, or NULL on error
Notes:
     (1) An error message is returned if any pix has something other
         than 1 bpp or 8 bpp depth, and the centroid from that pix
         is saved as (0, 0).

Definition at line 1478 of file morphapp.c.

References L_CLONE, makePixelCentroidTab8(), makePixelSumTab8(), pixaGetCount(), pixaGetPix(), pixCentroid(), pixDestroy(), ptaAddPt(), and ptaCreate().

◆ pixaExtendByMorph()

PIXA* pixaExtendByMorph ( PIXA pixas,
l_int32  type,
l_int32  niters,
SEL sel,
l_int32  include 
)

pixaExtendByMorph()

Parameters
[in]pixas
[in]typeL_MORPH_DILATE, L_MORPH_ERODE
[in]niters
[in]selused for dilation, erosion; uses 2x2 if null
[in]include1 to include a copy of the input pixas in pixad; 0 to omit
Returns
pixad with derived pix, using all iterations, or NULL on error
Notes:
   (1) This dilates or erodes every pix in pixas, iteratively,
       using the input Sel (or, if null, a 2x2 Sel by default),
       and puts the results in pixad.
   (2) If niters <= 0, this is a no-op; it returns a clone of pixas.
   (3) If include == 1, the output pixad contains all the pix
       in pixas.  Otherwise, it doesn't, but pixaJoin() can be
       used later to join pixas with pixad.

Definition at line 904 of file morphapp.c.

References L_CLONE, and pixaCopy().

◆ pixaExtendByScaling()

PIXA* pixaExtendByScaling ( PIXA pixas,
NUMA nasc,
l_int32  type,
l_int32  include 
)

pixaExtendByScaling()

Parameters
[in]pixas
[in]nascnuma of scaling factors
[in]typeL_HORIZ, L_VERT, L_BOTH_DIRECTIONS
[in]include1 to include a copy of the input pixas in pixad; 0 to omit
Returns
pixad with derived pix, using all scalings, or NULL on error
Notes:
   (1) This scales every pix in pixas by each factor in nasc.
       and puts the results in pixad.
   (2) If include == 1, the output pixad contains all the pix
       in pixas.  Otherwise, it doesn't, but pixaJoin() can be
       used later to join pixas with pixad.

Definition at line 976 of file morphapp.c.

References numaGetCount().

Referenced by recogMakeBootDigitTemplates().

◆ pixaMorphSequenceByComponent()

PIXA* pixaMorphSequenceByComponent ( PIXA pixas,
const char *  sequence,
l_int32  minw,
l_int32  minh 
)

pixaMorphSequenceByComponent()

Parameters
[in]pixasof 1 bpp pix
[in]sequencestring specifying sequence
[in]minwmin width to consider; use 0 or 1 for any width
[in]minhmin height to consider; use 0 or 1 for any height
Returns
pixad, or NULL on error
Notes:
     (1) See pixMorphSequence() for composing operation sequences.
     (2) This operates separately on each c.c. in the input pixa.
     (3) You can specify that the width and/or height must equal
         or exceed a minimum size for the operation to take place.
     (4) The input pixa should have a boxa giving the locations
         of the pix components.

Definition at line 268 of file morphapp.c.

References L_CLONE, L_COPY, L_INSERT, pixaAddBox(), pixaAddPix(), pixaCreate(), pixaDestroy(), pixaGetBox(), pixaGetBoxaCount(), pixaGetCount(), pixaGetPix(), pixaGetPixDimensions(), pixDestroy(), and pixMorphCompSequence().

Referenced by pixMorphSequenceByComponent().

◆ pixaMorphSequenceByRegion()

PIXA* pixaMorphSequenceByRegion ( PIX pixs,
PIXA pixam,
const char *  sequence,
l_int32  minw,
l_int32  minh 
)

pixaMorphSequenceByRegion()

Parameters
[in]pixs1 bpp
[in]pixamof 1 bpp mask elements
[in]sequencestring specifying sequence
[in]minwmin width to consider; use 0 or 1 for any width
[in]minhmin height to consider; use 0 or 1 for any height
Returns
pixad, or NULL on error
Notes:
     (1) See pixMorphSequence() for composing operation sequences.
     (2) This operates separately on each region in the input pixs
         defined by the components in pixam.
     (3) You can specify that the width and/or height of a mask
         component must equal or exceed a minimum size for the
         operation to take place.
     (4) The input pixam should have a boxa giving the locations
         of the regions in pixs.

Definition at line 430 of file morphapp.c.

◆ pixCentroid()

l_ok pixCentroid ( PIX pix,
l_int32 *  centtab,
l_int32 *  sumtab,
l_float32 *  pxave,
l_float32 *  pyave 
)

pixCentroid()

Parameters
[in]pix1 or 8 bpp
[in]centtab[optional] table for finding centroids; can be null
[in]sumtab[optional] table for finding pixel sums; can be null
[out]pxavex coordinate of centroid, relative to the UL corner of the pix
[out]pyavey coordinate of centroid, relative to the UL corner of the pix
Returns
0 if OK, 1 on error
Notes:
     (1) The sum and centroid tables are only used for 1 bpp.
     (2) Any table not passed in will be made internally and destroyed
         after use.

Definition at line 1533 of file morphapp.c.

References makePixelCentroidTab8(), makePixelSumTab8(), pixGetData(), pixGetDimensions(), and pixSetPadBits().

Referenced by pixaAccumulateSamples(), pixaCentroids(), pixCompareWithTranslation(), and recogTrainingFinished().

◆ pixDisplayMatchedPattern()

PIX* pixDisplayMatchedPattern ( PIX pixs,
PIX pixp,
PIX pixe,
l_int32  x0,
l_int32  y0,
l_uint32  color,
l_float32  scale,
l_int32  nlevels 
)

pixDisplayMatchedPattern()

Parameters
[in]pixsinput image, 1 bpp
[in]pixppattern to be removed from image, 1 bpp
[in]pixeimage after erosion by Sel that approximates pixp
[in]x0,y0center of Sel
[in]colorto paint the matched patterns; 0xrrggbb00
[in]scalereduction factor for output pixd
[in]nlevelsif scale < 1.0, threshold to this number of levels
Returns
pixd 8 bpp, colormapped, or NULL on error
Notes:
   (1) A 4 bpp colormapped image is generated.
   (2) If scale <= 1.0, do scale to gray for the output, and threshold
       to nlevels of gray.
   (3) You can use various functions in selgen to create a Sel
       that will generate pixe from pixs.
   (4) This function is applied after pixe has been computed.
       It finds the centroid of each c.c., and colors the output
       pixels using pixp (appropriately aligned) as a stencil.
       Alignment is done using the origin of the Sel and the
       centroid of the eroded image to place the stencil pixp.

Definition at line 792 of file morphapp.c.

◆ pixExtractBoundary()

PIX* pixExtractBoundary ( PIX pixs,
l_int32  type 
)

pixExtractBoundary()

Parameters
[in]pixs1 bpp
[in]type0 for background pixels; 1 for foreground pixels
Returns
pixd, or NULL on error
Notes:
     (1) Extracts the fg or bg boundary pixels for each component.
         Components are assumed to end at the boundary of pixs.

Definition at line 111 of file morphapp.c.

References pixDilateBrick(), pixErodeBrick(), and pixXor().

Referenced by pixFindStrokeLength().

◆ pixFastTophat()

PIX* pixFastTophat ( PIX pixs,
l_int32  xsize,
l_int32  ysize,
l_int32  type 
)

pixFastTophat()

Parameters
[in]pixs8 bpp
[in]xsizewidth of max/min op, smoothing; any integer >= 1
[in]ysizeheight of max/min op, smoothing; any integer >= 1
[in]typeL_TOPHAT_WHITE: image - min L_TOPHAT_BLACK: max - image
Returns
pixd, or NULL on error
Notes:
     (1) Don't be fooled. This is NOT a tophat.  It is a tophat-like
         operation, where the result is similar to what you'd get
         if you used an erosion instead of an opening, or a dilation
         instead of a closing.
     (2) Instead of opening or closing at full resolution, it does
         a fast downscale/minmax operation, then a quick small smoothing
         at low res, a replicative expansion of the "background"
         to full res, and finally a removal of the background level
         from the input image.  The smoothing step may not be important.
     (3) It does not remove noise as well as a tophat, but it is
         5 to 10 times faster.
         If you need the preciseness of the tophat, don't use this.
     (4) The L_TOPHAT_WHITE flag emphasizes small bright regions,
         whereas the L_TOPHAT_BLACK flag emphasizes small dark regions.

Definition at line 1362 of file morphapp.c.

◆ pixHDome()

PIX* pixHDome ( PIX pixs,
l_int32  height,
l_int32  connectivity 
)

pixHDome()

Parameters
[in]pixs8 bpp, filling mask
[in]heightof seed below the filling maskhdome; must be >= 0
[in]connectivity4 or 8
Returns
pixd 8 bpp, or NULL on error
Notes:
     (1) It is more efficient to use a connectivity of 4 for the fill.
     (2) This fills bumps to some level, and extracts the unfilled
         part of the bump.  To extract the troughs of basins, first
         invert pixs and then apply pixHDome().
     (3) It is useful to compare the HDome operation with the TopHat.
         The latter extracts peaks or valleys that have a width
         not exceeding the size of the structuring element used
         in the opening or closing, rsp.  The height of the peak is
         irrelevant.  By contrast, for the HDome, the gray seedfill
         is used to extract all peaks that have a height not exceeding
         a given value, regardless of their width!
     (4) Slightly more precisely, suppose you set 'height' = 40.
         Then all bumps in pixs with a height greater than or equal
         to 40 become, in pixd, bumps with a max value of exactly 40.
         All shorter bumps have a max value in pixd equal to the height
         of the bump.
     (5) The method: the filling mask, pixs, is the image whose peaks
         are to be extracted.  The height of a peak is the distance
         between the top of the peak and the highest "leak" to the
         outside -- think of a sombrero, where the leak occurs
         at the highest point on the rim.
           (a) Generate a seed, pixd, by subtracting some value, p, from
               each pixel in the filling mask, pixs.  The value p is
               the 'height' input to this function.
           (b) Fill in pixd starting with this seed, clipping by pixs,
               in the way described in seedfillGrayLow().  The filling
               stops before the peaks in pixs are filled.
               For peaks that have a height > p, pixd is filled to
               the level equal to the (top-of-the-peak - p).
               For peaks of height < p, the peak is left unfilled
               from its highest saddle point (the leak to the outside).
           (c) Subtract the filled seed (pixd) from the filling mask (pixs).
         Note that in this procedure, everything is done starting
         with the filling mask, pixs.
     (6) For segmentation, the resulting image, pixd, can be thresholded
         and used as a seed for another filling operation.

Definition at line 1306 of file morphapp.c.

◆ pixIntersectionOfMorphOps()

PIX* pixIntersectionOfMorphOps ( PIX pixs,
SELA sela,
l_int32  type 
)

pixIntersectionOfMorphOps()

Parameters
[in]pixs1 bpp
[in]sela
[in]typeL_MORPH_DILATE, etc.
Returns
pixd intersection of the specified morphological operation on pixs for each Sel in the Sela, or NULL on error

Definition at line 558 of file morphapp.c.

◆ pixMorphGradient()

PIX* pixMorphGradient ( PIX pixs,
l_int32  hsize,
l_int32  vsize,
l_int32  smoothing 
)

pixMorphGradient()

Parameters
[in]pixs8 bpp
[in]hsizesel width; must be odd; origin implicitly in center
[in]vsizesel height
[in]smoothinghalf-width of convolution smoothing filter. The width is (2 * smoothing + 1, so 0 is no-op.
Returns
pixd, or NULL on error

Definition at line 1424 of file morphapp.c.

◆ pixMorphSequenceByComponent()

PIX* pixMorphSequenceByComponent ( PIX pixs,
const char *  sequence,
l_int32  connectivity,
l_int32  minw,
l_int32  minh,
BOXA **  pboxa 
)

pixMorphSequenceByComponent()

Parameters
[in]pixs1 bpp
[in]sequencestring specifying sequence
[in]connectivity4 or 8
[in]minwmin width to consider; use 0 or 1 for any width
[in]minhmin height to consider; use 0 or 1 for any height
[out]pboxa[optional] return boxa of c.c. in pixs
Returns
pixd, or NULL on error
Notes:
     (1) See pixMorphSequence() for composing operation sequences.
     (2) This operates separately on each c.c. in the input pix.
     (3) The dilation does NOT increase the c.c. size; it is clipped
         to the size of the original c.c.   This is necessary to
         keep the c.c. independent after the operation.
     (4) You can specify that the width and/or height must equal
         or exceed a minimum size for the operation to take place.
     (5) Use NULL for boxa to avoid returning the boxa.

Definition at line 198 of file morphapp.c.

References boxaDestroy(), L_CLONE, PIX_PAINT, pixaDestroy(), pixaGetBoxa(), pixaGetBoxGeometry(), pixaGetCount(), pixaGetPix(), pixaMorphSequenceByComponent(), pixConnComp(), pixCreateTemplate(), pixDestroy(), and pixRasterop().

◆ pixMorphSequenceByRegion()

PIX* pixMorphSequenceByRegion ( PIX pixs,
PIX pixm,
const char *  sequence,
l_int32  connectivity,
l_int32  minw,
l_int32  minh,
BOXA **  pboxa 
)

pixMorphSequenceByRegion()

Parameters
[in]pixs1 bpp
[in]pixmmask specifying regions
[in]sequencestring specifying sequence
[in]connectivity4 or 8, used on mask
[in]minwmin width to consider; use 0 or 1 for any width
[in]minhmin height to consider; use 0 or 1 for any height
[out]pboxa[optional] return boxa of c.c. in pixm
Returns
pixd, or NULL on error
Notes:
     (1) See pixMorphCompSequence() for composing operation sequences.
     (2) This operates separately on the region in pixs corresponding
         to each c.c. in the mask pixm.  It differs from
         pixMorphSequenceByComponent() in that the latter does not have
         a pixm (mask), but instead operates independently on each
         component in pixs.
     (3) Dilation will NOT increase the region size; the result
         is clipped to the size of the mask region.  This is necessary
         to make regions independent after the operation.
     (4) You can specify that the width and/or height of a region must
         equal or exceed a minimum size for the operation to take place.
     (5) Use NULL for pboxa to avoid returning the boxa.

Definition at line 351 of file morphapp.c.

◆ pixMorphSequenceMasked()

PIX* pixMorphSequenceMasked ( PIX pixs,
PIX pixm,
const char *  sequence,
l_int32  dispsep 
)

pixMorphSequenceMasked()

Parameters
[in]pixs1 bpp
[in]pixm[optional] 1 bpp mask
[in]sequencestring specifying sequence of operations
[in]dispsephorizontal separation in pixels between successive displays; use zero to suppress display
Returns
pixd, or NULL on error
Notes:
     (1) This applies the morph sequence to the image, but only allows
         changes in pixs for pixels under the background of pixm.
     (5) If pixm is NULL, this is just pixMorphSequence().

Definition at line 151 of file morphapp.c.

References pixCombineMasked(), and pixMorphSequence().

◆ pixRemoveMatchedPattern()

l_ok pixRemoveMatchedPattern ( PIX pixs,
PIX pixp,
PIX pixe,
l_int32  x0,
l_int32  y0,
l_int32  dsize 
)

pixRemoveMatchedPattern()

Parameters
[in]pixsinput image, 1 bpp
[in]pixppattern to be removed from image, 1 bpp
[in]pixeimage after erosion by Sel that approximates pixp
[in]x0,y0center of Sel
[in]dsizenumber of pixels on each side by which pixp is dilated before being subtracted from pixs; valid values are {0, 1, 2, 3, 4}
Returns
0 if OK, 1 on error
Notes:
   (1) This is in-place.
   (2) You can use various functions in selgen to create a Sel
       that is used to generate pixe from pixs.
   (3) This function is applied after pixe has been computed.
       It finds the centroid of each c.c., and subtracts
       (the appropriately dilated version of) pixp, with the center
       of the Sel used to align pixp with pixs.

Definition at line 687 of file morphapp.c.

◆ pixRunHistogramMorph()

NUMA* pixRunHistogramMorph ( PIX pixs,
l_int32  runtype,
l_int32  direction,
l_int32  maxsize 
)

pixRunHistogramMorph()

Parameters
[in]pixs1 bpp
[in]runtypeL_RUN_OFF, L_RUN_ON
[in]directionL_HORIZ, L_VERT
[in]maxsizesize of largest runlength counted
Returns
numa of run-lengths

Definition at line 1106 of file morphapp.c.

◆ pixSeedfillMorph()

PIX* pixSeedfillMorph ( PIX pixs,
PIX pixm,
l_int32  maxiters,
l_int32  connectivity 
)

pixSeedfillMorph()

Parameters
[in]pixsseed
[in]pixmmask
[in]maxitersuse 0 to go to completion
[in]connectivity4 or 8
Returns
pixd after filling into the mask or NULL on error
Notes:
   (1) This is in general a very inefficient method for filling
       from a seed into a mask.  Use it for a small number of iterations,
       but if you expect more than a few iterations, use
       pixSeedfillBinary().
   (2) We use a 3x3 brick SEL for 8-cc filling and a 3x3 plus SEL for 4-cc.

Definition at line 1044 of file morphapp.c.

◆ pixSelectiveConnCompFill()

PIX* pixSelectiveConnCompFill ( PIX pixs,
l_int32  connectivity,
l_int32  minw,
l_int32  minh 
)

pixSelectiveConnCompFill()

Parameters
[in]pixs1 bpp
[in]connectivity4 or 8
[in]minwmin width to consider; use 0 or 1 for any width
[in]minhmin height to consider; use 0 or 1 for any height
Returns
pix with holes filled in selected c.c., or NULL on error

Definition at line 616 of file morphapp.c.

◆ pixTophat()

PIX* pixTophat ( PIX pixs,
l_int32  hsize,
l_int32  vsize,
l_int32  type 
)

pixTophat()

Parameters
[in]pixs1 bpp
[in]hsizeof Sel; must be odd; origin implicitly in center
[in]vsizeditto
[in]typeL_TOPHAT_WHITE: image - opening L_TOPHAT_BLACK: closing - image
Returns
pixd, or NULL on error
Notes:
     (1) Sel is a brick with all elements being hits
     (2) If hsize = vsize = 1, returns an image with all 0 data.
     (3) The L_TOPHAT_WHITE flag emphasizes small bright regions,
         whereas the L_TOPHAT_BLACK flag emphasizes small dark regions.
         The L_TOPHAT_WHITE tophat can be accomplished by doing a
         L_TOPHAT_BLACK tophat on the inverse, or v.v.

Definition at line 1206 of file morphapp.c.

◆ pixUnionOfMorphOps()

PIX* pixUnionOfMorphOps ( PIX pixs,
SELA sela,
l_int32  type 
)

pixUnionOfMorphOps()

Parameters
[in]pixs1 bpp
[in]sela
[in]typeL_MORPH_DILATE, etc.
Returns
pixd union of the specified morphological operation on pixs for each Sel in the Sela, or NULL on error

Definition at line 505 of file morphapp.c.