Leptonica  1.83.1
Image processing and image analysis suite
textops.c File Reference
#include <string.h>
#include "allheaders.h"

Go to the source code of this file.

Functions

static l_int32 stringAllWhitespace (char *textstr, l_int32 *pval)
 
static l_int32 stringLeadingWhitespace (char *textstr, l_int32 *pval)
 
PIXpixAddSingleTextblock (PIX *pixs, L_BMF *bmf, const char *textstr, l_uint32 val, l_int32 location, l_int32 *poverflow)
 
PIXpixAddTextlines (PIX *pixs, L_BMF *bmf, const char *textstr, l_uint32 val, l_int32 location)
 
l_ok pixSetTextblock (PIX *pixs, L_BMF *bmf, const char *textstr, l_uint32 val, l_int32 x0, l_int32 y0, l_int32 wtext, l_int32 firstindent, l_int32 *poverflow)
 
l_ok pixSetTextline (PIX *pixs, L_BMF *bmf, const char *textstr, l_uint32 val, l_int32 x0, l_int32 y0, l_int32 *pwidth, l_int32 *poverflow)
 
PIXApixaAddTextNumber (PIXA *pixas, L_BMF *bmf, NUMA *na, l_uint32 val, l_int32 location)
 
PIXApixaAddTextlines (PIXA *pixas, L_BMF *bmf, SARRAY *sa, l_uint32 val, l_int32 location)
 
l_ok pixaAddPixWithText (PIXA *pixa, PIX *pixs, l_int32 reduction, L_BMF *bmf, const char *textstr, l_uint32 val, l_int32 location)
 
SARRAYbmfGetLineStrings (L_BMF *bmf, const char *textstr, l_int32 maxw, l_int32 firstindent, l_int32 *ph)
 
NUMAbmfGetWordWidths (L_BMF *bmf, const char *textstr, SARRAY *sa)
 
l_ok bmfGetStringWidth (L_BMF *bmf, const char *textstr, l_int32 *pw)
 
SARRAYsplitStringToParagraphs (char *textstr, l_int32 splitflag)
 

Detailed Description


   Font layout
      PIX             *pixAddSingleTextblock()
      PIX             *pixAddTextlines()
      l_int32          pixSetTextblock()
      l_int32          pixSetTextline()
      PIXA            *pixaAddTextNumber()
      PIXA            *pixaAddTextlines()
      l_int32          pixaAddPixWithText()

   Text size estimation and partitioning
      SARRAY          *bmfGetLineStrings()
      NUMA            *bmfGetWordWidths()
      l_int32          bmfGetStringWidth()

   Text splitting
      SARRAY          *splitStringToParagraphs()
      static l_int32   stringAllWhitespace()
      static l_int32   stringLeadingWhitespace()

   This is a simple utility to put text on images.  One font and style
   is provided, with a variety of pt sizes.  For example, to put a
   line of green 10 pt text on an image, with the beginning baseline
   at (50, 50):
       L_Bmf  *bmf = bmfCreate(NULL, 10);
       const char *textstr = "This is a funny cat";
       pixSetTextline(pixs, bmf, textstr, 0x00ff0000, 50, 50, NULL, NULL);

   The simplest interfaces for adding text to an image are
   pixAddTextlines() and pixAddSingleTextblock().
   For example, to add the same text in red, centered, below the image:
       Pix *pixd = pixAddTextlines(pixs, bmf, textstr, 0xff000000,
                                   L_ADD_BELOW);  // red text

   To add text to all pix in a pixa, generating a new pixa, use
   either an sarray to hold the strings for each pix, or use the
   strings in the text field of each pix; e.g.,
       Pixa *pixa2 = pixaAddTextlines(pixa1, bmf, sa, 0x0000ff00,
                                   L_ADD_LEFT);  // blue text
       Pixa *pixa2 = pixaAddTextlines(pixa1, bmf, NULL, 0x00ff0000,
                                   L_ADD_RIGHT);  // green text

Definition in file textops.c.

Function Documentation

◆ bmfGetLineStrings()

SARRAY* bmfGetLineStrings ( L_BMF bmf,
const char *  textstr,
l_int32  maxw,
l_int32  firstindent,
l_int32 *  ph 
)

bmfGetLineStrings()

Parameters
[in]bmf
[in]textstr
[in]maxwmax width of a text line in pixels
[in]firstindentindentation of first line, in x-widths
[out]phheight required to hold text bitmap
Returns
sarray of text strings for each line, or NULL on error
Notes:
     (1) Divides the input text string into an array of text strings,
         each of which will fit within maxw bits of width.

Definition at line 857 of file textops.c.

References bmfGetWidth(), bmfGetWordWidths(), L_INSERT, L_Bmf::lineheight, numaDestroy(), numaGetCount(), numaGetIValue(), sarrayAddString(), sarrayCreate(), sarrayCreateWordsFromString(), sarrayDestroy(), sarrayGetCount(), sarrayToStringRange(), L_Bmf::spacewidth, and L_Bmf::vertlinesep.

◆ bmfGetStringWidth()

l_ok bmfGetStringWidth ( L_BMF bmf,
const char *  textstr,
l_int32 *  pw 
)

bmfGetStringWidth()

Parameters
[in]bmf
[in]textstr
[out]pwwidth of text string, in pixels for the font represented by the bmf
Returns
0 if OK, 1 on error

Definition at line 970 of file textops.c.

References bmfGetWidth(), and L_Bmf::kernwidth.

Referenced by bmfGetWordWidths().

◆ bmfGetWordWidths()

NUMA* bmfGetWordWidths ( L_BMF bmf,
const char *  textstr,
SARRAY sa 
)

bmfGetWordWidths()

Parameters
[in]bmf
[in]textstr
[in]saof individual words
Returns
numa of word lengths in pixels for the font represented by the bmf, or NULL on error

Definition at line 931 of file textops.c.

References bmfGetStringWidth(), L_NOCOPY, numaAddNumber(), numaCreate(), sarrayGetCount(), and sarrayGetString().

Referenced by bmfGetLineStrings().

◆ pixaAddPixWithText()

l_ok pixaAddPixWithText ( PIXA pixa,
PIX pixs,
l_int32  reduction,
L_BMF bmf,
const char *  textstr,
l_uint32  val,
l_int32  location 
)

pixaAddPixWithText()

Parameters
[in]pixa
[in]pixsany depth, colormap ok
[in]reductioninteger subsampling factor
[in]bmf[optional] bitmap font data
[in]textstr[optional] text string to be added
[in]valcolor to set the text
[in]locationL_ADD_ABOVE, L_ADD_BELOW, L_ADD_LEFT, L_ADD_RIGHT
Returns
0 if OK, 1 on error.
Notes:
     (1) This function generates a new pix with added text, and adds
         it by insertion into the pixa.
     (2) If the input pixs is not cmapped and not 32 bpp, it is
         converted to 32 bpp rgb.  val is a standard 32 bpp pixel,
         expressed as 0xrrggbb00.  If there is a colormap, this does
         the best it can to use the requested color, or something close.
     (3) if bmf == NULL, generate an 8 pt font; this takes about 5 msec.
     (4) If textstr == NULL, use the text field in the pix.
     (5) In general, the text string can be written in multiple lines;
         use newlines as the separators.
     (6) Typical usage is for debugging, where the pixa of labeled images
         is used to generate a pdf.  Suggest using 1.0 for scalefactor.

Definition at line 777 of file textops.c.

References bmfCreate(), L_ADD_ABOVE, L_ADD_BELOW, L_ADD_LEFT, L_ADD_RIGHT, L_COPY, pixaAddPix(), pixClone(), pixGetText(), and pixScaleByIntSampling().

◆ pixaAddTextlines()

PIXA* pixaAddTextlines ( PIXA pixas,
L_BMF bmf,
SARRAY sa,
l_uint32  val,
l_int32  location 
)

pixaAddTextlines()

Parameters
[in]pixasinput pixa; colormap ok
[in]bmfbitmap font data
[in]sa[optional] sarray; use text embedded in each pix if null
[in]valcolor to set the text
[in]locationL_ADD_ABOVE, L_ADD_BELOW, L_ADD_LEFT, L_ADD_RIGHT
Returns
pixad new pixa with rendered text, or NULL on error
Notes:
     (1) This function adds one or more lines of text externally to
         each pix, in a position given by location.  In all cases,
         the pix is expanded as necessary to accommodate the text.
     (2) val is the pixel value to be painted through the font mask.
         It should be chosen to agree with the depth of pixs.
         If it is out of bounds, an intermediate value is chosen.
         For RGB, use hex notation: 0xRRGGBB00, where RR is the
         hex representation of the red intensity, etc.
     (3) If sa == NULL, use the text embedded in each pix.  In all
         cases, newlines in the text string are used to separate the
         lines of text that are added to the pix.
     (4) If sa has a smaller count than pixa, issue a warning
         and do not use any embedded text.
     (5) If there is a colormap, this does the best it can to use
         the requested color, or something similar to it.

Definition at line 709 of file textops.c.

References L_ADD_ABOVE, L_ADD_BELOW, L_ADD_LEFT, L_ADD_RIGHT, L_CLONE, L_INSERT, L_NOCOPY, pixaAddPix(), pixaCreate(), pixAddTextlines(), pixaGetCount(), pixaGetPix(), pixDestroy(), pixGetText(), sarrayGetCount(), and sarrayGetString().

◆ pixaAddTextNumber()

PIXA* pixaAddTextNumber ( PIXA pixas,
L_BMF bmf,
NUMA na,
l_uint32  val,
l_int32  location 
)

pixaAddTextNumber()

Parameters
[in]pixasinput pixa; colormap ok
[in]bmfbitmap font data
[in]na[optional] number array; use 1 ... n if null
[in]valcolor to set the text
[in]locationL_ADD_ABOVE, L_ADD_BELOW, L_ADD_LEFT, L_ADD_RIGHT
Returns
pixad new pixa with rendered numbers, or NULL on error
Notes:
     (1) Typical usage is for labelling each pix in a pixa with a number.
     (2) This function paints numbers external to each pix, in a position
         given by location.  In all cases, the pix is expanded on
         on side and the number is painted over white in the added region.
     (3) val is the pixel value to be painted through the font mask.
         It should be chosen to agree with the depth of pixs.
         If it is out of bounds, an intermediate value is chosen.
         For RGB, use hex notation: 0xRRGGBB00, where RR is the
         hex representation of the red intensity, etc.
     (4) If na == NULL, number each pix sequentially, starting with 1.
     (5) If there is a colormap, this does the best it can to use
         the requested color, or something similar to it.

Definition at line 641 of file textops.c.

References L_ADD_ABOVE, L_ADD_BELOW, L_ADD_LEFT, L_ADD_RIGHT, L_CLONE, L_INSERT, numaGetIValue(), pixaAddPix(), pixaCreate(), pixAddTextlines(), pixaGetCount(), pixaGetPix(), and pixDestroy().

Referenced by pixaSelectToPdf().

◆ pixAddSingleTextblock()

PIX* pixAddSingleTextblock ( PIX pixs,
L_BMF bmf,
const char *  textstr,
l_uint32  val,
l_int32  location,
l_int32 *  poverflow 
)

pixAddSingleTextblock()

Parameters
[in]pixsinput pix; colormap ok
[in]bmfbitmap font data
[in]textstr[optional] text string to be added
[in]valcolor to set the text
[in]locationL_ADD_ABOVE, L_ADD_AT_TOP, L_ADD_AT_BOT, L_ADD_BELOW
[out]poverflow[optional] 1 if text overflows allocated region and is clipped; 0 otherwise
Returns
pixd new pix with rendered text, or either a copy, or NULL on error
Notes:
     (1) This function paints a set of lines of text over an image.
         If location is L_ADD_ABOVE or L_ADD_BELOW, the pix size
         is expanded with a border and rendered over the border.
     (2) val is the pixel value to be painted through the font mask.
         It should be chosen to agree with the depth of pixs.
         If it is out of bounds, an intermediate value is chosen.
         For RGB, use hex notation: 0xRRGGBB00, where RR is the
         hex representation of the red intensity, etc.
     (3) If textstr == NULL, use the text field in the pix.
     (4) If there is a colormap, this does the best it can to use
         the requested color, or something similar to it.
     (5) Typical usage is for labelling a pix with some text data.

Definition at line 120 of file textops.c.

References L_ADD_ABOVE, L_ADD_AT_BOT, L_ADD_AT_TOP, L_ADD_BELOW, pixCopy(), pixGetDimensions(), and pixGetText().

Referenced by boxaDisplayTiled(), dewarpaShowArrays(), fpixaDisplayQuadtree(), pixaDisplayTiledWithText(), pixDisplayColorArray(), recogDisplayOutlier(), and recogShowMatch().

◆ pixAddTextlines()

PIX* pixAddTextlines ( PIX pixs,
L_BMF bmf,
const char *  textstr,
l_uint32  val,
l_int32  location 
)

pixAddTextlines()

Parameters
[in]pixsinput pix; colormap ok
[in]bmfbitmap font data
[in]textstr[optional] text string to be added
[in]valcolor to set the text
[in]locationL_ADD_ABOVE, L_ADD_BELOW, L_ADD_LEFT, L_ADD_RIGHT
Returns
pixd new pix with rendered text, or either a copy, or NULL on error
Notes:
     (1) This function expands an image as required to paint one or
         more lines of text adjacent to the image.  If bmf == NULL,
         this returns a copy.  If above or below, the lines are
         centered with respect to the image; if left or right, they
         are left justified.
     (2) val is the pixel value to be painted through the font mask.
         It should be chosen to agree with the depth of pixs.
         If it is out of bounds, an intermediate value is chosen.
         For RGB, use hex notation: 0xRRGGBB00, where RR is the
         hex representation of the red intensity, etc.
     (3) If textstr == NULL, use the text field in the pix.  The
         text field contains one or most "lines" of text, where newlines
         are used as line separators.
     (4) If there is a colormap, this does the best it can to use
         the requested color, or something similar to it.
     (5) Typical usage is for labelling a pix with some text data.

Definition at line 274 of file textops.c.

References L_ADD_ABOVE, L_ADD_BELOW, L_ADD_LEFT, L_ADD_RIGHT, pixCopy(), pixGetDimensions(), and pixGetText().

Referenced by pixaAddTextlines(), pixaAddTextNumber(), pixaConvertToNUpPixa(), pixaDisplayTiledByIndex(), recogShowPath(), and showExtractNumbers().

◆ pixSetTextblock()

l_ok pixSetTextblock ( PIX pixs,
L_BMF bmf,
const char *  textstr,
l_uint32  val,
l_int32  x0,
l_int32  y0,
l_int32  wtext,
l_int32  firstindent,
l_int32 *  poverflow 
)

pixSetTextblock()

Parameters
[in]pixsinput image
[in]bmfbitmap font data
[in]textstrblock text string to be set
[in]valcolor to set the text
[in]x0left edge for each line of text
[in]y0baseline location for the first text line
[in]wtextmax width of each line of generated text
[in]firstindentindentation of first line, in x-widths
[out]poverflow[optional] 0 if text is contained in input pix; 1 if it is clipped
Returns
0 if OK, 1 on error
Notes:
     (1) This function paints a set of lines of text over an image.
     (2) val is the pixel value to be painted through the font mask.
         It should be chosen to agree with the depth of pixs.
         If it is out of bounds, an intermediate value is chosen.
         For RGB, use hex notation: 0xRRGGBB00, where RR is the
         hex representation of the red intensity, etc.
         The last two hex digits are 00 (byte value 0), assigned to
         the A component.  Note that, as usual, RGBA proceeds from
         left to right in the order from MSB to LSB (see pix.h
         for details).
     (3) If there is a colormap, this does the best it can to use
         the requested color, or something similar to it.

Definition at line 435 of file textops.c.

References pixGetDimensions().

◆ pixSetTextline()

l_ok pixSetTextline ( PIX pixs,
L_BMF bmf,
const char *  textstr,
l_uint32  val,
l_int32  x0,
l_int32  y0,
l_int32 *  pwidth,
l_int32 *  poverflow 
)

pixSetTextline()

Parameters
[in]pixsinput image
[in]bmfbitmap font data
[in]textstrtext string to be set on the line
[in]valcolor to set the text
[in]x0left edge for first char
[in]y0baseline location for all text on line
[out]pwidth[optional] width of generated text
[out]poverflow[optional] 0 if text is contained in input pix; 1 if it is clipped
Returns
0 if OK, 1 on error
Notes:
     (1) This function paints a line of text over an image.
     (2) val is the pixel value to be painted through the font mask.
         It should be chosen to agree with the depth of pixs.
         If it is out of bounds, an intermediate value is chosen.
         For RGB, use hex notation: 0xRRGGBB00, where RR is the
         hex representation of the red intensity, etc.
         The last two hex digits are 00 (byte value 0), assigned to
         the A component.  Note that, as usual, RGBA proceeds from
         left to right in the order from MSB to LSB (see pix.h
         for details).
     (3) If there is a colormap, this does the best it can to use
         the requested color, or something similar to it.

Definition at line 546 of file textops.c.

◆ splitStringToParagraphs()

SARRAY* splitStringToParagraphs ( char *  textstr,
l_int32  splitflag 
)

splitStringToParagraphs()

Parameters
[in]textstrtext string
[in]splitflagsee enum in bmf.h; valid values in {1,2,3}
Returns
sarray where each string is a paragraph of the input, or NULL on error.

Definition at line 1012 of file textops.c.

References L_COPY, L_INSERT, L_NOCOPY, sarrayAddString(), sarrayCreate(), sarrayCreateLinesFromString(), sarrayDestroy(), sarrayGetCount(), sarrayGetString(), sarrayToString(), SPLIT_ON_BLANK_LINE, SPLIT_ON_BOTH, SPLIT_ON_LEADING_WHITE, stringAllWhitespace(), and stringLeadingWhitespace().

◆ stringAllWhitespace()

static l_int32 stringAllWhitespace ( char *  textstr,
l_int32 *  pval 
)
static

stringAllWhitespace()

Parameters
[in]textstrtext string
[out]pval1 if all whitespace; 0 otherwise
Returns
0 if OK, 1 on error

Definition at line 1060 of file textops.c.

Referenced by splitStringToParagraphs().

◆ stringLeadingWhitespace()

static l_int32 stringLeadingWhitespace ( char *  textstr,
l_int32 *  pval 
)
static

stringLeadingWhitespace()

Parameters
[in]textstrtext string
[out]pval1 if leading char is [space] or [tab]; 0 otherwise
Returns
0 if OK, 1 on error

Definition at line 1090 of file textops.c.

Referenced by splitStringToParagraphs().