tesseract::ImageThresholder Class Reference

#include <thresholder.h>

Public Member Functions
	ImageThresholder ()
virtual	~ImageThresholder ()
virtual void	Clear ()
	Destroy the Pix if there is one, freeing memory. More...
bool	IsEmpty () const
	Return true if no image has been set. More...
void	SetImage (const unsigned char *imagedata, int width, int height, int bytes_per_pixel, int bytes_per_line)
void	SetRectangle (int left, int top, int width, int height)
virtual void	GetImageSizes (int *left, int *top, int *width, int *height, int *imagewidth, int *imageheight)
bool	IsColor () const
	Return true if the source image is color. More...
bool	IsBinary () const
	Returns true if the source image is binary. More...
int	GetScaleFactor () const
void	SetSourceYResolution (int ppi)
int	GetSourceYResolution () const
int	GetScaledYResolution () const
void	SetEstimatedResolution (int ppi)
int	GetScaledEstimatedResolution () const
void	SetImage (const Image pix)
virtual bool	ThresholdToPix (Image *pix)
	Returns false on error. More...
virtual std::tuple< bool, Image, Image, Image >	Threshold (TessBaseAPI *api, ThresholdMethod method)
virtual Image	GetPixRectThresholds ()
Image	GetPixRect ()
virtual Image	GetPixRectGrey ()

Protected Member Functions
virtual void	Init ()
	Common initialization shared between SetImage methods. More...
bool	IsFullImage () const
	Return true if we are processing the full image. More...
void	OtsuThresholdRectToPix (Image src_pix, Image *out_pix) const
void	ThresholdRectToPix (Image src_pix, int num_channels, const std::vector< int > &thresholds, const std::vector< int > &hi_values, Image *pix) const

Protected Attributes
Image	pix_
int	image_width_
	Width of source pix_. More...
int	image_height_
	Height of source pix_. More...
int	pix_channels_
	Number of 8-bit channels in pix_. More...
int	pix_wpl_
	Words per line of pix_. More...
int	scale_
	Scale factor from original image. More...
int	yres_
	y pixels/inch in source image. More...
int	estimated_res_
	Resolution estimate from text size. More...
int	rect_left_
int	rect_top_
int	rect_width_
int	rect_height_

Detailed Description

Base class for all tesseract image thresholding classes. Specific classes can add new thresholding methods by overriding ThresholdToPix. Each instance deals with a single image, but the design is intended to be useful for multiple calls to SetRectangle and ThresholdTo* if desired.

Definition at line 45 of file thresholder.h.

Constructor & Destructor Documentation

ImageThresholder()

tesseract::ImageThresholder::ImageThresholder

(

)

Definition at line 42 of file thresholder.cpp.

    : pix_(nullptr)
    , image_width_(0)
    , image_height_(0)
    , pix_channels_(0)
    , pix_wpl_(0)
    , scale_(1)
    , yres_(300)
    , estimated_res_(300) {
  SetRectangle(0, 0, 0, 0);
}

~ImageThresholder()

tesseract::ImageThresholder::~ImageThresholder ( )

virtual

Definition at line 54 of file thresholder.cpp.

                                    {
  Clear();
}

Member Function Documentation

Clear()

void tesseract::ImageThresholder::Clear ( )

virtual

Destroy the Pix if there is one, freeing memory.

Definition at line 59 of file thresholder.cpp.

                             {
  pix_.destroy();
}

GetImageSizes()

void tesseract::ImageThresholder::GetImageSizes ( int *  left, int *  top, int *  width, int *  height, int *  imagewidth, int *  imageheight  )

virtual

Get enough parameters to be able to rebuild bounding boxes in the original image (not just within the rectangle). Left and top are enough with top-down coordinates, but the height of the rectangle and the image are needed for bottom-up.

Definition at line 148 of file thresholder.cpp.

                                                       {
  *left = rect_left_;
  *top = rect_top_;
  *width = rect_width_;
  *height = rect_height_;
  *imagewidth = image_width_;
  *imageheight = image_height_;
}

GetPixRect()

Image tesseract::ImageThresholder::GetPixRect

(

)

Get a clone/copy of the source image rectangle. The returned Pix must be pixDestroyed. This function will be used in the future by the page layout analysis, and the layout analysis that uses it will only be available with Leptonica, so there is no raw equivalent.

Definition at line 351 of file thresholder.cpp.

                                   {
  if (IsFullImage()) {
    // Just clone the whole thing.
    return pix_.clone();
  } else {
    // Crop to the given rectangle.
    Box *box = boxCreate(rect_left_, rect_top_, rect_width_, rect_height_);
    Image cropped = pixClipRectangle(pix_, box, nullptr);
    boxDestroy(&box);
    return cropped;
  }
}

GetPixRectGrey()

Image tesseract::ImageThresholder::GetPixRectGrey ( )

virtual

Definition at line 368 of file thresholder.cpp.

                                       {
  auto pix = GetPixRect(); // May have to be reduced to grey.
  int depth = pixGetDepth(pix);
  if (depth != 8 || pixGetColormap(pix)) {
    if (depth == 24) {
      auto tmp = pixConvert24To32(pix);
      pix.destroy();
      pix = tmp;
    }
    auto result = pixConvertTo8(pix, false);
    pix.destroy();
    return result;
  }
  return pix;
}

GetPixRectThresholds()

Image tesseract::ImageThresholder::GetPixRectThresholds ( )

virtual

Definition at line 324 of file thresholder.cpp.

                                             {
  if (IsBinary()) {
    return nullptr;
  }
  Image pix_grey = GetPixRectGrey();
  int width = pixGetWidth(pix_grey);
  int height = pixGetHeight(pix_grey);
  std::vector<int> thresholds;
  std::vector<int> hi_values;
  OtsuThreshold(pix_grey, 0, 0, width, height, thresholds, hi_values);
  pix_grey.destroy();
  Image pix_thresholds = pixCreate(width, height, 8);
  int threshold = thresholds[0] > 0 ? thresholds[0] : 128;
  pixSetAllArbitrary(pix_thresholds, threshold);
  return pix_thresholds;
}

GetScaledEstimatedResolution()

int tesseract::ImageThresholder::GetScaledEstimatedResolution ( ) const

inline

Definition at line 115 of file thresholder.h.

                                           {
    return scale_ * estimated_res_;
  }

GetScaledYResolution()

int tesseract::ImageThresholder::GetScaledYResolution ( ) const

inline

Definition at line 102 of file thresholder.h.

                                   {
    return scale_ * yres_;
  }

GetScaleFactor()

int tesseract::ImageThresholder::GetScaleFactor ( ) const

inline

Definition at line 88 of file thresholder.h.

                             {
    return scale_;
  }

GetSourceYResolution()

int tesseract::ImageThresholder::GetSourceYResolution ( ) const

inline

Definition at line 99 of file thresholder.h.

                                   {
    return yres_;
  }

Init()

void tesseract::ImageThresholder::Init ( )

protectedvirtual

Common initialization shared between SetImage methods.

Definition at line 342 of file thresholder.cpp.

                            {
  SetRectangle(0, 0, image_width_, image_height_);
}

IsBinary()

bool tesseract::ImageThresholder::IsBinary ( ) const

inline

Returns true if the source image is binary.

Definition at line 84 of file thresholder.h.

                        {
    return pix_channels_ == 0;
  }

IsColor()

bool tesseract::ImageThresholder::IsColor ( ) const

inline

Return true if the source image is color.

Definition at line 79 of file thresholder.h.

                       {
    return pix_channels_ >= 3;
  }

IsEmpty()

bool tesseract::ImageThresholder::IsEmpty

(

)

const

Return true if no image has been set.

Definition at line 64 of file thresholder.cpp.

                                     {
  return pix_ == nullptr;
}

IsFullImage()

bool tesseract::ImageThresholder::IsFullImage ( ) const

inlineprotected

Return true if we are processing the full image.

Definition at line 165 of file thresholder.h.

                           {
    return rect_left_ == 0 && rect_top_ == 0 && rect_width_ == image_width_ &&
           rect_height_ == image_height_;
  }

OtsuThresholdRectToPix()

void tesseract::ImageThresholder::OtsuThresholdRectToPix ( Image  src_pix, Image *  out_pix  ) const

protected

Definition at line 385 of file thresholder.cpp.

                                                                                 {
  std::vector<int> thresholds;
  std::vector<int> hi_values;
 
  int num_channels = OtsuThreshold(src_pix, rect_left_, rect_top_, rect_width_, rect_height_,
                                   thresholds, hi_values);
  // only use opencl if compiled w/ OpenCL and selected device is opencl
#ifdef USE_OPENCL
  OpenclDevice od;
  if (num_channels == 4 && od.selectedDeviceIsOpenCL() && rect_top_ == 0 && rect_left_ == 0) {
    od.ThresholdRectToPixOCL((unsigned char *)pixGetData(src_pix), num_channels,
                             pixGetWpl(src_pix) * 4, &thresholds[0], &hi_values[0], out_pix /*pix_OCL*/,
                             rect_height_, rect_width_, rect_top_, rect_left_);
  } else {
#endif
    ThresholdRectToPix(src_pix, num_channels, thresholds, hi_values, out_pix);
#ifdef USE_OPENCL
  }
#endif
}

SetEstimatedResolution()

void tesseract::ImageThresholder::SetEstimatedResolution ( int  ppi )

inline

Definition at line 110 of file thresholder.h.

                                       {
    estimated_res_ = ppi;
  }

SetImage() [1/2]

void tesseract::ImageThresholder::SetImage

(

const Image

pix

)

Pix vs raw, which to use? Pix is the preferred input for efficiency, since raw buffers are copied. SetImage for Pix clones its input, so the source pix may be pixDestroyed immediately after, but may not go away until after the Thresholder has finished with it.

Definition at line 163 of file thresholder.cpp.

                                               {
  if (pix_ != nullptr) {
    pix_.destroy();
  }
  Image src = pix;
  int depth;
  pixGetDimensions(src, &image_width_, &image_height_, &depth);
  // Convert the image as necessary so it is one of binary, plain RGB, or
  // 8 bit with no colormap. Guarantee that we always end up with our own copy,
  // not just a clone of the input.
  if (depth > 1 && depth < 8) {
    pix_ = pixConvertTo8(src, false);
  } else {
    pix_ = src.copy();
  }
  depth = pixGetDepth(pix_);
  pix_channels_ = depth / 8;
  pix_wpl_ = pixGetWpl(pix_);
  scale_ = 1;
  estimated_res_ = yres_ = pixGetYRes(pix_);
  Init();
}

SetImage() [2/2]

void tesseract::ImageThresholder::SetImage	(	const unsigned char *	imagedata,
		int	width,
		int	height,
		int	bytes_per_pixel,
		int	bytes_per_line
	)

SetImage makes a copy of all the image data, so it may be deleted immediately after this call. Greyscale of 8 and color of 24 or 32 bits per pixel may be given. Palette color images will not work properly and must be converted to 24 bit. Binary images of 1 bit per pixel may also be given but they must be byte packed with the MSB of the first byte being the first pixel, and a one pixel is WHITE. For binary images set bytes_per_pixel=0.

Definition at line 76 of file thresholder.cpp.

                                                                         {
  int bpp = bytes_per_pixel * 8;
  if (bpp == 0) {
    bpp = 1;
  }
  Image pix = pixCreate(width, height, bpp == 24 ? 32 : bpp);
  l_uint32 *data = pixGetData(pix);
  int wpl = pixGetWpl(pix);
  switch (bpp) {
    case 1:
      for (int y = 0; y < height; ++y, data += wpl, imagedata += bytes_per_line) {
        for (int x = 0; x < width; ++x) {
          if (imagedata[x / 8] & (0x80 >> (x % 8))) {
            CLEAR_DATA_BIT(data, x);
          } else {
            SET_DATA_BIT(data, x);
          }
        }
      }
      break;
 
    case 8:
      // Greyscale just copies the bytes in the right order.
      for (int y = 0; y < height; ++y, data += wpl, imagedata += bytes_per_line) {
        for (int x = 0; x < width; ++x) {
          SET_DATA_BYTE(data, x, imagedata[x]);
        }
      }
      break;
 
    case 24:
      // Put the colors in the correct places in the line buffer.
      for (int y = 0; y < height; ++y, imagedata += bytes_per_line) {
        for (int x = 0; x < width; ++x, ++data) {
          SET_DATA_BYTE(data, COLOR_RED, imagedata[3 * x]);
          SET_DATA_BYTE(data, COLOR_GREEN, imagedata[3 * x + 1]);
          SET_DATA_BYTE(data, COLOR_BLUE, imagedata[3 * x + 2]);
        }
      }
      break;
 
    case 32:
      // Maintain byte order consistency across different endianness.
      for (int y = 0; y < height; ++y, imagedata += bytes_per_line, data += wpl) {
        for (int x = 0; x < width; ++x) {
          data[x] = (imagedata[x * 4] << 24) | (imagedata[x * 4 + 1] << 16) |
                    (imagedata[x * 4 + 2] << 8) | imagedata[x * 4 + 3];
        }
      }
      break;
 
    default:
      tprintf("Cannot convert RAW image to Pix with bpp = %d\n", bpp);
  }
  SetImage(pix);
  pix.destroy();
}

SetRectangle()

void tesseract::ImageThresholder::SetRectangle	(	int	left,
		int	top,
		int	width,
		int	height
	)

Store the coordinates of the rectangle to process for later use. Doesn't actually do any thresholding.

Definition at line 137 of file thresholder.cpp.

                                                                            {
  rect_left_ = left;
  rect_top_ = top;
  rect_width_ = width;
  rect_height_ = height;
}

SetSourceYResolution()

void tesseract::ImageThresholder::SetSourceYResolution ( int  ppi )

inline

Definition at line 95 of file thresholder.h.

                                     {
    yres_ = ppi;
    estimated_res_ = ppi;
  }

Threshold()

std::tuple< bool, Image, Image, Image > tesseract::ImageThresholder::Threshold ( TessBaseAPI *  api, ThresholdMethod  method  )

virtual

Definition at line 186 of file thresholder.cpp.

                                                                              {
  Image pix_binary = nullptr;
  Image pix_thresholds = nullptr;
 
  if (pix_channels_ == 0) {
    // We have a binary image, but it still has to be copied, as this API
    // allows the caller to modify the output.
    Image original = GetPixRect();
    pix_binary = original.copy();
    original.destroy();
    return std::make_tuple(true, nullptr, pix_binary, nullptr);
  }
 
  auto pix_grey = GetPixRectGrey();
 
  int r;
 
  l_int32 pix_w, pix_h;
  pixGetDimensions(pix_grey, &pix_w, &pix_h, nullptr);
 
  bool thresholding_debug;
  api->GetBoolVariable("thresholding_debug", &thresholding_debug);
  if (thresholding_debug) {
    tprintf("\nimage width: %d  height: %d  ppi: %d\n", pix_w, pix_h, yres_);
  }
 
  if (method == ThresholdMethod::Sauvola) {
    int window_size;
    double window_size_factor;
    api->GetDoubleVariable("thresholding_window_size", &window_size_factor);
    window_size = window_size_factor * yres_;
    window_size = std::max(7, window_size);
    window_size = std::min(pix_w < pix_h ? pix_w - 3 : pix_h - 3, window_size);
    int half_window_size = window_size / 2;
 
    // factor for image division into tiles; >= 1
    l_int32 nx, ny;
    // tiles size will be approx. 250 x 250 pixels
    nx = std::max(1, (pix_w + 125) / 250);
    ny = std::max(1, (pix_h + 125) / 250);
    auto xrat = pix_w / nx;
    auto yrat = pix_h / ny;
    if (xrat < half_window_size + 2) {
      nx = pix_w / (half_window_size + 2);
    }
    if (yrat < half_window_size + 2) {
      ny = pix_h / (half_window_size + 2);
    }
 
    double kfactor;
    api->GetDoubleVariable("thresholding_kfactor", &kfactor);
    kfactor = std::max(0.0, kfactor);
 
    if (thresholding_debug) {
      tprintf("window size: %d  kfactor: %.3f  nx:%d  ny: %d\n", window_size, kfactor, nx, ny);
    }
 
    r = pixSauvolaBinarizeTiled(pix_grey, half_window_size, kfactor, nx, ny,
                               (PIX**)pix_thresholds,
                                (PIX**)pix_binary);
  } else { // if (method == ThresholdMethod::LeptonicaOtsu)
    int tile_size;
    double tile_size_factor;
    api->GetDoubleVariable("thresholding_tile_size", &tile_size_factor);
    tile_size = tile_size_factor * yres_;
    tile_size = std::max(16, tile_size);
 
    int smooth_size;
    double smooth_size_factor;
    api->GetDoubleVariable("thresholding_smooth_kernel_size",
                         &smooth_size_factor);
    smooth_size_factor = std::max(0.0, smooth_size_factor);
    smooth_size = smooth_size_factor * yres_;
    int half_smooth_size = smooth_size / 2;
 
    double score_fraction;
    api->GetDoubleVariable("thresholding_score_fraction", &score_fraction);
 
    if (thresholding_debug) {
      tprintf("tile size: %d  smooth_size: %d  score_fraction: %.2f\n", tile_size, smooth_size, score_fraction);
    }
 
    r = pixOtsuAdaptiveThreshold(pix_grey, tile_size, tile_size,
                                 half_smooth_size, half_smooth_size,
                                 score_fraction,
                                 (PIX**)pix_thresholds,
                                 (PIX**)pix_binary);
  }
 
  bool ok = (r == 0);
  return std::make_tuple(ok, pix_grey, pix_binary, pix_thresholds);
}

ThresholdRectToPix()

void tesseract::ImageThresholder::ThresholdRectToPix ( Image  src_pix, int  num_channels, const std::vector< int > &  thresholds, const std::vector< int > &  hi_values, Image *  pix  ) const

protected

Threshold the rectangle, taking everything except the src_pix from the class, using thresholds/hi_values to the output pix. NOTE that num_channels is the size of the thresholds and hi_values

Definition at line 410 of file thresholder.cpp.

                                                                                             {
  *pix = pixCreate(rect_width_, rect_height_, 1);
  uint32_t *pixdata = pixGetData(*pix);
  int wpl = pixGetWpl(*pix);
  int src_wpl = pixGetWpl(src_pix);
  uint32_t *srcdata = pixGetData(src_pix);
  pixSetXRes(*pix, pixGetXRes(src_pix));
  pixSetYRes(*pix, pixGetYRes(src_pix));
  for (int y = 0; y < rect_height_; ++y) {
    const uint32_t *linedata = srcdata + (y + rect_top_) * src_wpl;
    uint32_t *pixline = pixdata + y * wpl;
    for (int x = 0; x < rect_width_; ++x) {
      bool white_result = true;
      for (int ch = 0; ch < num_channels; ++ch) {
        int pixel = GET_DATA_BYTE(linedata, (x + rect_left_) * num_channels + ch);
        if (hi_values[ch] >= 0 && (pixel > thresholds[ch]) == (hi_values[ch] == 0)) {
          white_result = false;
          break;
        }
      }
      if (white_result) {
        CLEAR_DATA_BIT(pixline, x);
      } else {
        SET_DATA_BIT(pixline, x);
      }
    }
  }
}

ThresholdToPix()

bool tesseract::ImageThresholder::ThresholdToPix ( Image *  pix )

virtual

Returns false on error.

Threshold the source image as efficiently as possible to the output Pix. Creates a Pix and sets pix to point to the resulting pointer. Caller must use pixDestroy to free the created Pix. Returns false on error.

Definition at line 285 of file thresholder.cpp.

                                                {
  if (image_width_ > INT16_MAX || image_height_ > INT16_MAX) {
    tprintf("Image too large: (%d, %d)\n", image_width_, image_height_);
    return false;
  }
  Image original = GetPixRect();
  if (pix_channels_ == 0) {
    // We have a binary image, but it still has to be copied, as this API
    // allows the caller to modify the output.
    *pix = original.copy();
  } else {
    if (pixGetColormap(original)) {
      Image tmp;
      Image without_cmap =
          pixRemoveColormap(original, REMOVE_CMAP_BASED_ON_SRC);
      int depth = pixGetDepth(without_cmap);
      if (depth > 1 && depth < 8) {
        tmp = pixConvertTo8(without_cmap, false);
      } else {
        tmp = without_cmap.copy();
      }
      without_cmap.destroy();
      OtsuThresholdRectToPix(tmp, pix);
      tmp.destroy();
    } else {
      OtsuThresholdRectToPix(pix_, pix);
    }
  }
  original.destroy();
  return true;
}

Member Data Documentation

estimated_res_

int tesseract::ImageThresholder::estimated_res_

protected

Resolution estimate from text size.

Definition at line 192 of file thresholder.h.

image_height_

int tesseract::ImageThresholder::image_height_

protected

Height of source pix_.

Definition at line 186 of file thresholder.h.

image_width_

int tesseract::ImageThresholder::image_width_

protected

Width of source pix_.

Definition at line 185 of file thresholder.h.

pix_

Image tesseract::ImageThresholder::pix_

protected

Clone or other copy of the source Pix. The pix will always be PixDestroy()ed on destruction of the class.

Definition at line 183 of file thresholder.h.

pix_channels_

int tesseract::ImageThresholder::pix_channels_

protected

Number of 8-bit channels in pix_.

Definition at line 187 of file thresholder.h.

pix_wpl_

int tesseract::ImageThresholder::pix_wpl_

protected

Words per line of pix_.

Definition at line 188 of file thresholder.h.

rect_height_

int tesseract::ImageThresholder::rect_height_

protected

Definition at line 196 of file thresholder.h.

rect_left_

int tesseract::ImageThresholder::rect_left_

protected

Definition at line 193 of file thresholder.h.

rect_top_

int tesseract::ImageThresholder::rect_top_

protected

Definition at line 194 of file thresholder.h.

rect_width_

int tesseract::ImageThresholder::rect_width_

protected

Definition at line 195 of file thresholder.h.

scale_

int tesseract::ImageThresholder::scale_

protected

Scale factor from original image.

Definition at line 190 of file thresholder.h.

yres_

int tesseract::ImageThresholder::yres_

protected

y pixels/inch in source image.

Definition at line 191 of file thresholder.h.

---

The documentation for this class was generated from the following files:

• /media/home/debian/src/github/tesseract-ocr/tesseract/src/ccmain/thresholder.h
• /media/home/debian/src/github/tesseract-ocr/tesseract/src/ccmain/thresholder.cpp