Leptonica  1.82.0
Image processing and image analysis suite
pixlabel.c File Reference
#include <string.h>
#include <math.h>
#include "allheaders.h"

Go to the source code of this file.

Functions

PIXpixConnCompTransform (PIX *pixs, l_int32 connect, l_int32 depth)
 
PIXpixConnCompAreaTransform (PIX *pixs, l_int32 connect)
 
l_ok pixConnCompIncrInit (PIX *pixs, l_int32 conn, PIX **ppixd, PTAA **pptaa, l_int32 *pncc)
 
l_int32 pixConnCompIncrAdd (PIX *pixs, PTAA *ptaa, l_int32 *pncc, l_float32 x, l_float32 y, l_int32 debug)
 
l_ok pixGetSortedNeighborValues (PIX *pixs, l_int32 x, l_int32 y, l_int32 conn, l_int32 **pneigh, l_int32 *pnvals)
 
PIXpixLocToColorTransform (PIX *pixs)
 

Detailed Description

    Label pixels by an index for connected component membership
          PIX         *pixConnCompTransform()
    Label pixels by the area of their connected component
          PIX         *pixConnCompAreaTransform()
    Label pixels to allow incremental computation of connected components
          l_int32      pixConnCompIncrInit()
          l_int32      pixConnCompIncrAdd()
          l_int32      pixGetSortedNeighborValues()
    Label pixels with spatially-dependent color coding
          PIX         *pixLocToColorTransform()
 Pixels get labelled in various ways throughout the leptonica library,
 but most of the labelling is implicit, where the new value isn't
 even considered to be a label -- it is just a transformed pixel value
 that may be transformed again by another operation.  Quantization
 by thresholding, and dilation by a structuring element, are examples
 of these typical image processing operations.
 However, there are some explicit labelling procedures that are useful
 as end-points of analysis, where it typically would not make sense
 to do further image processing on the result.  Assigning false color
 based on pixel properties is an example of such labelling operations.
 Such operations typically have 1 bpp input images, and result
 in grayscale or color images.
 The procedures in this file are concerned with such explicit labelling.
 Some of these labelling procedures are also in other places in leptonica:
   runlength.c:
      This file has two labelling transforms based on runlengths:
      pixStrokeWidthTransform() and pixvRunlengthTransform().
      The pixels are labelled based on the width of the "stroke" to
      which they belong, or on the length of the horizontal or
      vertical run in which they are a member.  Runlengths can easily
      be filtered using a threshold.
   pixafunc2.c:
      This file has an operation, pixaDisplayRandomCmap(), that
      randomly labels pix in a pixa (that are typically found using
      pixConnComp) with up to 256 values, and assigns each value to
      a random colormap color.
   seedfill.c:
      This file has pixDistanceFunction(), that labels each pixel with
      its distance from either the foreground or the background.

Definition in file pixlabel.c.

Function Documentation

◆ pixConnCompAreaTransform()

PIX* pixConnCompAreaTransform ( PIX pixs,
l_int32  connect 
)

pixConnCompAreaTransform()

Parameters
[in]pixs1 bpp
[in]connectconnectivity: 4 or 8
Returns
pixd 32 bpp, 1 spp, or NULL on error
Notes:
     (1) The pixel values in pixd label the area of the fg component
         to which the pixel belongs.  Pixels in the bg are labelled 0.
     (2) For purposes of visualization, the output can be converted
         to 8 bpp, using pixConvert32To8() or pixMaxDynamicRange().

Definition at line 196 of file pixlabel.c.

◆ pixConnCompIncrAdd()

l_int32 pixConnCompIncrAdd ( PIX pixs,
PTAA ptaa,
l_int32 *  pncc,
l_float32  x,
l_float32  y,
l_int32  debug 
)

pixConnCompIncrAdd()

Parameters
[in]pixs32 bpp, with pixels labeled by c.c.
[in]ptaawith each pta of pixel locations indexed by c.c.
[out]pnccnumber of c.c
[in]x,ylocation of added pixel
[in]debug0 for no output; otherwise output whenever debug <= nvals, up to debug == 3
Returns
-1 if nothing happens; 0 if a pixel is added; 1 on error
Notes:
     (1) This adds a pixel and updates the labeled connected components.
         Before calling this function, initialize the process using
         pixConnCompIncrInit().
     (2) As a result of adding a pixel, one of the following can happen,
         depending on the number of neighbors with non-zero value:
         (a) nothing: the pixel is already a member of a c.c.
         (b) no neighbors: a new component is added, increasing the
             number of c.c.
         (c) one neighbor: the pixel is added to an existing c.c.
         (d) more than one neighbor: the added pixel causes joining of
             two or more c.c., reducing the number of c.c.  A maximum
             of 4 c.c. can be joined.
     (3) When two c.c. are joined, the pixels in the larger index are
         relabeled to those of the smaller in pixs, and their locations
         are transferred to the pta with the smaller index in the ptaa.
         The pta corresponding to the larger index is then deleted.
     (4) This is an efficient implementation of a "union-find" operation,
         which supports the generation and merging of disjoint sets
         of pixels.  This function can be called about 1.3 million times
         per second.

Definition at line 353 of file pixlabel.c.

◆ pixConnCompIncrInit()

l_ok pixConnCompIncrInit ( PIX pixs,
l_int32  conn,
PIX **  ppixd,
PTAA **  pptaa,
l_int32 *  pncc 
)

pixConnCompIncrInit()

Parameters
[in]pixs1 bpp
[in]connconnectivity: 4 or 8
[out]ppixd32 bpp, with c.c. labelled
[out]pptaawith pixel locations indexed by c.c.
[out]pnccinitial number of c.c.
Returns
0 if OK, 1 on error
Notes:
     (1) This labels the connected components in a 1 bpp pix, and
         additionally sets up a ptaa that lists the locations of pixels
         in each of the components.
     (2) It can be used to initialize the output image and arrays for
         an application that maintains information about connected
         components incrementally as pixels are added.
     (3) pixs can be empty or have some foreground pixels.
     (4) The connectivity is stored in pixd->special.
     (5) Always initialize with the first pta in ptaa being empty
         and representing the background value (index 0) in the pix.

Definition at line 269 of file pixlabel.c.

◆ pixConnCompTransform()

PIX* pixConnCompTransform ( PIX pixs,
l_int32  connect,
l_int32  depth 
)

pixConnCompTransform()

Parameters
[in]pixs1 bpp
[in]connectconnectivity: 4 or 8
[in]depthof pixd: 8 or 16 bpp; use 0 for auto determination
Returns
pixd 8, 16 or 32 bpp, or NULL on error
Notes:
     (1) pixd is 8, 16 or 32 bpp, and the pixel values label the
         fg component, starting with 1.  Pixels in the bg are labelled 0.
     (2) If depth = 0, the depth of pixd is 8 if the number of c.c.
         is less than 254, 16 if the number of c.c is less than 0xfffe,
         and 32 otherwise.
     (3) If depth = 8, the assigned label for the n-th component is
         1 + n % 254.  We use mod 254 because 0 is uniquely assigned
         to black: e.g., see pixcmapCreateRandom().  Likewise,
         if depth = 16, the assigned label uses mod(2^16 - 2), and
         if depth = 32, no mod is taken.

Definition at line 116 of file pixlabel.c.

◆ pixGetSortedNeighborValues()

l_ok pixGetSortedNeighborValues ( PIX pixs,
l_int32  x,
l_int32  y,
l_int32  conn,
l_int32 **  pneigh,
l_int32 *  pnvals 
)

pixGetSortedNeighborValues()

Parameters
[in]pixs8, 16 or 32 bpp, with pixels labeled by c.c.
[in]x,ylocation of pixel
[in]conn4 or 8 connected neighbors
[out]pneigharray of integers, to be filled with the values of the neighbors, if any
[out]pnvalsthe number of unique neighbor values found
Returns
0 if OK, 1 on error
Notes:
     (1) The returned neigh array is the unique set of neighboring
         pixel values, of size nvals, sorted from smallest to largest.
         The value 0, which represents background pixels that do
         not belong to any set of connected components, is discarded.
     (2) If there are no neighbors, this returns neigh = NULL; otherwise,
         the caller must free the array.
     (3) For either 4 or 8 connectivity, the maximum number of unique
         neighbor values is 4.

Definition at line 483 of file pixlabel.c.

◆ pixLocToColorTransform()

PIX* pixLocToColorTransform ( PIX pixs)

pixLocToColorTransform()

Parameters
[in]pixs1 bpp
Returns
pixd 32 bpp rgb, or NULL on error
Notes:
     (1) This generates an RGB image where each component value
         is coded depending on the (x.y) location and the size
         of the fg connected component that the pixel in pixs belongs to.
         It is independent of the 4-fold orthogonal orientation, and
         only weakly depends on translations and small angle rotations.
         Background pixels are black.
     (2) Such encodings can be compared between two 1 bpp images
         by performing this transform and calculating the
         "earth-mover" distance on the resulting R,G,B histograms.

Definition at line 569 of file pixlabel.c.