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

Go to the source code of this file.

Functions

PIXTILINGpixTilingCreate (PIX *pixs, l_int32 nx, l_int32 ny, l_int32 w, l_int32 h, l_int32 xoverlap, l_int32 yoverlap)
 
void pixTilingDestroy (PIXTILING **ppt)
 
l_ok pixTilingGetCount (PIXTILING *pt, l_int32 *pnx, l_int32 *pny)
 
l_ok pixTilingGetSize (PIXTILING *pt, l_int32 *pw, l_int32 *ph)
 
PIXpixTilingGetTile (PIXTILING *pt, l_int32 i, l_int32 j)
 
l_ok pixTilingNoStripOnPaint (PIXTILING *pt)
 
l_ok pixTilingPaintTile (PIX *pixd, l_int32 i, l_int32 j, PIX *pixs, PIXTILING *pt)
 

Detailed Description


       PIXTILING       *pixTilingCreate()
       void            *pixTilingDestroy()
       l_int32          pixTilingGetCount()
       l_int32          pixTilingGetSize()
       PIX             *pixTilingGetTile()
       l_int32          pixTilingNoStripOnPaint()
       l_int32          pixTilingPaintTile()

  This provides a simple way to split an image into tiles
  and to perform operations independently on each tile.

  The tile created with pixTilingGetTile() can have pixels in
  adjacent tiles for computation.  The number of extra pixels
  on each side of the tile is given by an 'overlap' parameter
  to pixTilingCreate().  For tiles at the boundary of
  the input image, quasi-overlap pixels are created by reflection
  symmetry into the tile.

  Here's a typical intended usage.  Suppose you want to parallelize
  the operation on an image, by operating on tiles.  For each
  tile, you want to generate an in-place image result at the same
  resolution.  Suppose you choose a one-dimensional vertical tiling,
  where the desired tile width is 256 pixels and the overlap is
  30 pixels on left and right sides:

    PIX *pixd = pixCreateTemplate(pixs);  // output
    PIXTILING  *pt = pixTilingCreate(pixs, 0, 1, 256, 30, 0);
    pixTilingGetCount(pt, &nx, NULL);
    for (j = 0; j < nx; j++) {
        PIX *pixt = pixTilingGetTile(pt, 0, j);
        SomeInPlaceOperation(pixt, 30, 0, ...);
        pixTilingPaintTile(pixd, 0, j, pixt, pt);
        pixDestroy(&pixt);
    }

  In this example, note the following:
   ~ The unspecfified in-place operation could instead generate
     a new pix.  If this is done, the resulting pix must be the
     same size as pixt, because pixTilingPaintTile() makes that
     assumption, removing the overlap pixels before painting
     into the destination.
   ~ The 'overlap' parameters have been included in your function,
     to indicate which pixels are not in the exterior overlap region.
     You will need to change only pixels that are not in the overlap
     region, because those are the pixels that will be painted
     into the destination.
   ~ For tiles on the outside of the image, mirrored pixels are
     added to substitute for the overlap that is added to interior
     tiles.  This allows you to implement your function without
     reference to which tile it is; no special coding is necessary
     for pixels that are near the image boundary.
   ~ The tiles are labeled by (i, j) = (row, column),
     and in this example there is one row and nx columns.

Definition in file pixtiling.c.

Function Documentation

◆ pixTilingCreate()

PIXTILING* pixTilingCreate ( PIX pixs,
l_int32  nx,
l_int32  ny,
l_int32  w,
l_int32  h,
l_int32  xoverlap,
l_int32  yoverlap 
)

pixTilingCreate()

Parameters
[in]pixspix to be tiled; any depth; colormap OK
[in]nxnumber of tiles across image
[in]nynumber of tiles down image
[in]wdesired width of each tile
[in]hdesired height of each tile
[in]xoverlapoverlap into neighboring tiles on each side
[in]yoverlapoverlap into neighboring tiles above and below
Returns
pixtiling, or NULL on error
Notes:
     (1) We put a clone of pixs in the PixTiling.
     (2) The input to pixTilingCreate() for horizontal tiling can be
         either the number of tiles across the image or the approximate
         width of the tiles.  If the latter, the actual width will be
         determined by making all tiles but the last of equal width, and
         making the last as close to the others as possible.  The same
         consideration is applied independently to the vertical tiling.
         To specify tile width, set nx = 0; to specify the number of
         tiles horizontally across the image, set w = 0.
     (3) If pixs is to be tiled in one-dimensional strips, use ny = 1 for
         vertical strips and nx = 1 for horizontal strips.
     (4) The overlap must not be larger than the width or height of
         the leftmost or topmost tile(s).

Definition at line 123 of file pixtiling.c.

References PixTiling::h, PixTiling::nx, PixTiling::ny, PixTiling::pix, pixClone(), pixGetDimensions(), PixTiling::strip, PixTiling::w, PixTiling::xoverlap, and PixTiling::yoverlap.

◆ pixTilingDestroy()

void pixTilingDestroy ( PIXTILING **  ppt)

pixTilingDestroy()

Parameters
[in,out]pptwill be set to null before returning
Returns
void

Definition at line 179 of file pixtiling.c.

References PixTiling::pix, and pixDestroy().

◆ pixTilingGetCount()

l_ok pixTilingGetCount ( PIXTILING pt,
l_int32 *  pnx,
l_int32 *  pny 
)

pixTilingGetCount()

Parameters
[in]ptpixtiling
[out]pnx[optional] nx; can be null
[out]pny[optional] ny; can be null
Returns
0 if OK, 1 on error

Definition at line 208 of file pixtiling.c.

References PixTiling::nx, and PixTiling::ny.

Referenced by pixTilingGetTile().

◆ pixTilingGetSize()

l_ok pixTilingGetSize ( PIXTILING pt,
l_int32 *  pw,
l_int32 *  ph 
)

pixTilingGetSize()

Parameters
[in]ptpixtiling
[out]pw[optional] tile width; can be null
[out]ph[optional] tile height; can be null
Returns
0 if OK, 1 on error

Definition at line 231 of file pixtiling.c.

References PixTiling::h, and PixTiling::w.

Referenced by pixTilingGetTile().

◆ pixTilingGetTile()

PIX* pixTilingGetTile ( PIXTILING pt,
l_int32  i,
l_int32  j 
)

pixTilingGetTile()

Parameters
[in]ptpixtiling
[in]itile row index
[in]jtile column index
Returns
pixd tile with appropriate boundary (overlap) pixels added, or NULL on error

Definition at line 255 of file pixtiling.c.

References boxCreate(), boxDestroy(), PixTiling::pix, pixAddMirroredBorder(), pixClipRectangle(), pixClone(), pixDestroy(), pixGetDimensions(), pixTilingGetCount(), pixTilingGetSize(), PixTiling::xoverlap, and PixTiling::yoverlap.

◆ pixTilingNoStripOnPaint()

l_ok pixTilingNoStripOnPaint ( PIXTILING pt)

pixTilingNoStripOnPaint()

Parameters
[in]ptpixtiling
Returns
0 if OK, 1 on error
Notes:
     (1) The default for paint is to strip out the overlap pixels
         that are added by pixTilingGetTile().  However, some
         operations will generate an image with these pixels
         stripped off.  This tells the paint operation not
         to strip the added boundary pixels when painting.

Definition at line 368 of file pixtiling.c.

References PixTiling::strip.

◆ pixTilingPaintTile()

l_ok pixTilingPaintTile ( PIX pixd,
l_int32  i,
l_int32  j,
PIX pixs,
PIXTILING pt 
)

pixTilingPaintTile()

Parameters
[in]pixddest: paint tile onto this, without overlap
[in]itile row index
[in]jtile column index
[in]pixssource: tile to be painted from
[in]ptpixtiling struct
Returns
0 if OK, 1 on error

Definition at line 390 of file pixtiling.c.

References PixTiling::h, PixTiling::nx, PixTiling::ny, PIX_SRC, pixGetDimensions(), pixRasterop(), PixTiling::strip, PixTiling::w, PixTiling::xoverlap, and PixTiling::yoverlap.