ccmain/thresholder.h - platform/external/tesseract - Git at Google

 ///////////////////////////////////////////////////////////////////////
 // File:        thresholder.h
 // Description: Base API for thresolding images in tesseract.
 // Author:      Ray Smith
 // Created:     Mon May 12 11:00:15 PDT 2008
 //
 // (C) Copyright 2008, Google Inc.
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
 // You may obtain a copy of the License at
 // http://www.apache.org/licenses/LICENSE-2.0
 // Unless required by applicable law or agreed to in writing, software
 // distributed under the License is distributed on an "AS IS" BASIS,
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
 //
 ///////////////////////////////////////////////////////////////////////

 #ifndef TESSERACT_CCMAIN_THRESHOLDER_H__
 #define TESSERACT_CCMAIN_THRESHOLDER_H__

 class IMAGE;
 struct Pix;

 namespace tesseract {

 // Base class for all tesseract image thresholding classes.
 // Specific classes can add new thresholding methods by
 // overriding ThresholdToIMAGE and/or 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.
 class ImageThresholder {
  public:
   ImageThresholder();
   virtual ~ImageThresholder();

   // Destroy the Pix if there is one, freeing memory.
   virtual void Clear();

   // Return true if no image has been set.
   bool IsEmpty() const;

   // SetImage makes a copy of only the metadata, not the underlying
   // image buffer. It promises to treat the source as read-only in either case,
   // but in return assumes that the Pix or image buffer remain valid
   // throughout the life of the ImageThresholder.
   // 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.
   void SetImage(const unsigned char* imagedata, int width, int height,
                 int bytes_per_pixel, int bytes_per_line);

   // Store the coordinates of the rectangle to process for later use.
   // Doesn't actually do any thresholding.
   void SetRectangle(int left, int top, int width, int height);

   // 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.
   virtual void GetImageSizes(int* left, int* top, int* width, int* height,
                              int* imagewidth, int* imageheight);

   // Return true if HAVE_LIBLEPT and this thresholder implements the Pix
   // interface.
   virtual bool HasThresholdToPix() const;

   // Return true if the source image is color.
   bool IsColor() const {
     return image_bytespp_ >= 3;
   }

   // Threshold the source image as efficiently as possible to the output
   // tesseract IMAGE class.
   virtual void ThresholdToIMAGE(IMAGE* image);

 #ifdef HAVE_LIBLEPT
   // Pix vs raw, which to use?
   // Implementations should provide the ability to source and target Pix
   // where possible. A future version of Tesseract may choose to use Pix
   // as its internal representation and discard IMAGE altogether.
   // Because of that, an implementation that sources and targets Pix may end up
   // with less copies than an implementation that does not.
   // NOTE: Opposite to SetImage for raw images, SetImage for Pix clones its
   // input, so the source pix may be pixDestroyed immediately after.
   void SetImage(const Pix* pix);

   // 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.
   virtual void ThresholdToPix(Pix** pix);

   // 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.
   Pix* GetPixRect();
 #endif

  protected:
   // ----------------------------------------------------------------------
   // Utility functions that may be useful components for other thresholders.

   // Common initialization shared between SetImage methods.
   virtual void Init();

   // Return true if we are processing the full image.
   bool IsFullImage() const {
     return rect_left_ == 0 && rect_top_ == 0 &&
            rect_width_ == image_width_ && rect_height_ == image_height_;
   }

   // Otsu threshold the rectangle, taking everything except the image buffer
   // pointer from the class, to the output IMAGE.
   void OtsuThresholdRectToIMAGE(const unsigned char* imagedata,
                                 int bytes_per_pixel, int bytes_per_line,
                                 IMAGE* image) const;

   // Threshold the rectangle, taking everything except the image buffer pointer
   // from the class, using thresholds/hi_values to the output IMAGE.
   void ThresholdRectToIMAGE(const unsigned char* imagedata,
                             int bytes_per_pixel, int bytes_per_line,
                             const int* thresholds, const int* hi_values,
                             IMAGE* image) const;

   // Cut out the requested rectangle of the source raw binary image to the
   // output IMAGE.
   void CopyBinaryRectRawToIMAGE(IMAGE* image) const;

 #ifdef HAVE_LIBLEPT
   // Otsu threshold the rectangle, taking everything except the image buffer
   // pointer from the class, to the output Pix.
   void OtsuThresholdRectToPix(const unsigned char* imagedata,
                               int bytes_per_pixel, int bytes_per_line,
                               Pix** pix) const;

   // Threshold the rectangle, taking everything except the image buffer pointer
   // from the class, using thresholds/hi_values to the output IMAGE.
   void ThresholdRectToPix(const unsigned char* imagedata,
                           int bytes_per_pixel, int bytes_per_line,
                           const int* thresholds, const int* hi_values,
                           Pix** pix) const;

   // Copy the raw image rectangle, taking all data from the class, to the Pix.
   void RawRectToPix(Pix** pix) const;

   // Cut out the requested rectangle of the binary image to the output IMAGE.
   void CopyBinaryRectPixToIMAGE(IMAGE* image) const;
 #endif

  protected:
 #ifdef HAVE_LIBLEPT
   // Clone or other copy of the source Pix.
   // The pix will always be PixDestroy()ed on destruction of the class.
   Pix*                 pix_;
 #endif
   // Exactly one of pix_ and image_data_ is not NULL.
   const unsigned char* image_data_;     // Raw source image.

   int                  image_width_;    // Width of source image/pix.
   int                  image_height_;   // Height of source image/pix.
   int                  image_bytespp_;  // Bytes per pixel of source image/pix.
   int                  image_bytespl_;  // Bytes per line of source image/pix.
   // Limits of image rectangle to be processed.
   int                  rect_left_;
   int                  rect_top_;
   int                  rect_width_;
   int                  rect_height_;
 };

 }  // namespace tesseract.

 #endif  // TESSERACT_CCMAIN_THRESHOLDER_H__
	///////////////////////////////////////////////////////////////////////
	// File: thresholder.h
	// Description: Base API for thresolding images in tesseract.
	// Author: Ray Smith
	// Created: Mon May 12 11:00:15 PDT 2008
	//
	// (C) Copyright 2008, Google Inc.
	// Licensed under the Apache License, Version 2.0 (the "License");
	// you may not use this file except in compliance with the License.
	// You may obtain a copy of the License at
	// http://www.apache.org/licenses/LICENSE-2.0
	// Unless required by applicable law or agreed to in writing, software
	// distributed under the License is distributed on an "AS IS" BASIS,
	// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	// See the License for the specific language governing permissions and
	// limitations under the License.
	//
	///////////////////////////////////////////////////////////////////////

	#ifndef TESSERACT_CCMAIN_THRESHOLDER_H__
	#define TESSERACT_CCMAIN_THRESHOLDER_H__

	class IMAGE;
	struct Pix;

	namespace tesseract {

	// Base class for all tesseract image thresholding classes.
	// Specific classes can add new thresholding methods by
	// overriding ThresholdToIMAGE and/or 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.
	class ImageThresholder {
	public:
	ImageThresholder();
	virtual ~ImageThresholder();

	// Destroy the Pix if there is one, freeing memory.
	virtual void Clear();

	// Return true if no image has been set.
	bool IsEmpty() const;

	// SetImage makes a copy of only the metadata, not the underlying
	// image buffer. It promises to treat the source as read-only in either case,
	// but in return assumes that the Pix or image buffer remain valid
	// throughout the life of the ImageThresholder.
	// 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.
	void SetImage(const unsigned char* imagedata, int width, int height,
	int bytes_per_pixel, int bytes_per_line);

	// Store the coordinates of the rectangle to process for later use.
	// Doesn't actually do any thresholding.
	void SetRectangle(int left, int top, int width, int height);

	// 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.
	virtual void GetImageSizes(int* left, int* top, int* width, int* height,
	int* imagewidth, int* imageheight);

	// Return true if HAVE_LIBLEPT and this thresholder implements the Pix
	// interface.
	virtual bool HasThresholdToPix() const;

	// Return true if the source image is color.
	bool IsColor() const {
	return image_bytespp_ >= 3;
	}

	// Threshold the source image as efficiently as possible to the output
	// tesseract IMAGE class.
	virtual void ThresholdToIMAGE(IMAGE* image);

	#ifdef HAVE_LIBLEPT
	// Pix vs raw, which to use?
	// Implementations should provide the ability to source and target Pix
	// where possible. A future version of Tesseract may choose to use Pix
	// as its internal representation and discard IMAGE altogether.
	// Because of that, an implementation that sources and targets Pix may end up
	// with less copies than an implementation that does not.
	// NOTE: Opposite to SetImage for raw images, SetImage for Pix clones its
	// input, so the source pix may be pixDestroyed immediately after.
	void SetImage(const Pix* pix);

	// 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.
	virtual void ThresholdToPix(Pix** pix);

	// 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.
	Pix* GetPixRect();
	#endif

	protected:
	// ----------------------------------------------------------------------
	// Utility functions that may be useful components for other thresholders.

	// Common initialization shared between SetImage methods.
	virtual void Init();

	// Return true if we are processing the full image.
	bool IsFullImage() const {
	return rect_left_ == 0 && rect_top_ == 0 &&
	rect_width_ == image_width_ && rect_height_ == image_height_;
	}

	// Otsu threshold the rectangle, taking everything except the image buffer
	// pointer from the class, to the output IMAGE.
	void OtsuThresholdRectToIMAGE(const unsigned char* imagedata,
	int bytes_per_pixel, int bytes_per_line,
	IMAGE* image) const;

	// Threshold the rectangle, taking everything except the image buffer pointer
	// from the class, using thresholds/hi_values to the output IMAGE.
	void ThresholdRectToIMAGE(const unsigned char* imagedata,
	int bytes_per_pixel, int bytes_per_line,
	const int* thresholds, const int* hi_values,
	IMAGE* image) const;

	// Cut out the requested rectangle of the source raw binary image to the
	// output IMAGE.
	void CopyBinaryRectRawToIMAGE(IMAGE* image) const;

	#ifdef HAVE_LIBLEPT
	// Otsu threshold the rectangle, taking everything except the image buffer
	// pointer from the class, to the output Pix.
	void OtsuThresholdRectToPix(const unsigned char* imagedata,
	int bytes_per_pixel, int bytes_per_line,
	Pix** pix) const;

	// Threshold the rectangle, taking everything except the image buffer pointer
	// from the class, using thresholds/hi_values to the output IMAGE.
	void ThresholdRectToPix(const unsigned char* imagedata,
	int bytes_per_pixel, int bytes_per_line,
	const int* thresholds, const int* hi_values,
	Pix** pix) const;

	// Copy the raw image rectangle, taking all data from the class, to the Pix.
	void RawRectToPix(Pix** pix) const;

	// Cut out the requested rectangle of the binary image to the output IMAGE.
	void CopyBinaryRectPixToIMAGE(IMAGE* image) const;
	#endif

	protected:
	#ifdef HAVE_LIBLEPT
	// Clone or other copy of the source Pix.
	// The pix will always be PixDestroy()ed on destruction of the class.
	Pix* pix_;
	#endif
	// Exactly one of pix_ and image_data_ is not NULL.
	const unsigned char* image_data_; // Raw source image.

	int image_width_; // Width of source image/pix.
	int image_height_; // Height of source image/pix.
	int image_bytespp_; // Bytes per pixel of source image/pix.
	int image_bytespl_; // Bytes per line of source image/pix.
	// Limits of image rectangle to be processed.
	int rect_left_;
	int rect_top_;
	int rect_width_;
	int rect_height_;
	};

	} // namespace tesseract.

	#endif // TESSERACT_CCMAIN_THRESHOLDER_H__