whellvalue/3part/Cyclops/include/BarCodeDetector.h

/*!
 * \file BarCodeDetector.h
 * \date 2018/10/11
 *
 * \author Lin, Chi
 * Contact: lin.chi@hzleaper.com
 *
 *
 * \note
*/

#ifndef __BarCodeDetector_h_
#define __BarCodeDetector_h_

#include "StdUtils.h"
#include "CVUtils.h"
#include "CyclopsEnums.h"
#include "CyclopsModules.h"
#include "BarCodeQuality.h"

struct BarCodeParamPack;

/*! \brief Scan and decode 1D/2D code from given image and ROI.
*
* Check enum BarCodeType for the supported barcode types.
* Here's some note:
*   1. Make sure the barcode area is not too small in entire image.
*   2. Make sure the barcode is clear enough, say, at least 1 or 2 pixels for interval white.
*   3. If the barcode is diagonals, it's possible we miss it. Try rotate your image.
*
* 1) If you are using Cyclops as static library,
* 1.1) and you want global factory to manage the detector for you, initialize the detector
* via BarCodeDetector::getInstance().
* Example:
* \code{.cpp}
* BarCodeDetector::Ptr bcdPtr = BarCodeDetector::getInstance("detect sth");
* bcdPtr->setCodeType(BarCodeType::All1D); // detect all 1D types
* BarCodeType codeType; // the true type
* std::string codeData; // barcode content
* vector<Point2f> codePose; // barcode area
* bool ret = bcdPtr->detectBest(inputMat, roiVertexes, codeType, codeData, codePose); // return true if find anythin
*
* // delete it later
* BarCodeDetector::deleteInstance("detect sth");
* \endcode
*
* 1.2) or, if you wish to manage the detector yourself:
* \code{.cpp}
* BarCodeDetector::Ptr bcdPtr = std::make_shared<BarCodeDetector>(); // remember to hold the smart pointer
* // balabala, same as above
* // ...
* \endcode
*
* 2) If you are using Cyclops as dynamic library,
* initialize and manipulate the detector via CyclopsModules APIs.
* Example:
* \code{.cpp}
* // get a long-term detector, and give it an unique name
* BarCodeDetector::Ptr bcdPtr = GetModuleInstance<BarCodeDetector>("detect sth");
* // get for temporary usage
* BarCodeDetector::Ptr localBcdPtr = GetModuleInstance<BarCodeDetector>();
*
* // delete it later
* DeleteModuleInstance<BarCodeDetector>("detect sth");
* \endcode
*
*/
class BarCodeDetector : public ICyclopsModuleInstance
{
public:
	/*! \fn setCodeType
	 * Define symbologies (types of barcodes), default to BarCodeType::All, see also getCodeType()
	 * \fn getCodeType
	 * Get value of symbologies (types of barcodes), see also setCodeType()
	 */
	DECLARE_PARAMETER(BarCodeType, CodeType)
	/*! \fn setCheckSum
	 * Define whether decode and verification of a check digit for symbologies is performed where it is optional,
	 * default to true, see also getCheckSum()
	 * \fn getCheckSum
	 * Get value of whether decode and verification of a check digit for symbologies is performed where it is optional, see also setCheckSum()
	 */
	DECLARE_PARAMETER(bool, CheckSum)
	/*! \fn setMinLength
	 * Define minimum length of decoded characters in a valid symbol, default to 0 means using code types' defaults, see also getMinLength()
	 * \fn getMinLength
	 * Get value of minimum length of decoded characters in a valid symbol, see also setMinLength()
	 */
	DECLARE_PARAMETER(int, MinLength)
	/*! \fn setMaxLength
	 * Define maximum length of decoded characters in a valid symbol, default to 0 means using code types' defaults, see also getMaxLength()
	 * \fn getMaxLength
	 * Get value of maximum length of decoded characters in a valid symbol, see also setMaxLength()
	 */
	DECLARE_PARAMETER(int, MaxLength)
	/*! \fn setXDensity
	 * Define the density of the scanner passes horizontally, lower values scan more of the image at the cost of decreased performance.
	 * Default to 1, see also getXDensity()
	 * \fn getXDensity
	 * Get value of the density of the scanner passes horizontally, see also setXDensity()
	 */
	DECLARE_PARAMETER(int, XDensity)
	/*! \fn setYDensity
	 * Define the density of the scanner passes vertically, lower values scan more of the image at the cost of decreased performance.
	 * Default to 1, see also getYDensity()
	 * \fn getYDensity
	 * Get value of the density of the scanner passes vertically, see also setYDensity()
	 */
	DECLARE_PARAMETER(int, YDensity)
	/*! \fn setAllowDup
	 * Define whether duplicated symbols are allowed in multi-detection, default to false, see also getAllowDup()
	 * \fn getAllowDup
	 * Get value of whether duplicated symbols are allowed in multi-detection, see also setAllowDup()
	 */
	DECLARE_PARAMETER(bool, AllowDup)

public:
	BarCodeDetector(BarCodeType codeType) :
		mCodeType(codeType), mCheckSum(false), mMinLength(0), mMaxLength(0), mXDensity(1), mYDensity(1), mAllowDup(false)
	{}
	BarCodeDetector() :
		mCodeType(BarCodeType::All), mCheckSum(false), mMinLength(0), mMaxLength(0), mXDensity(1), mYDensity(1), mAllowDup(false)
	{}
	virtual ~BarCodeDetector() {}

	//! Smart pointer to hold an instance of BarCodeDetector
	typedef std::shared_ptr<BarCodeDetector> Ptr;
	DECL_GET_INSTANCE(BarCodeDetector::Ptr)

	/*! Detect the best barcode in the given image
	* @param img input image for detection
	* @param codeType output the result code type
	* @param codeData output the result code
	* @param codePose output the pose of barcode
	* @param codeQuality output the quality of barcode
	* @return true for found, false for not
	*/
	virtual bool detectBest(const Mat& img,
		BarCodeType& codeType,
		std::string& codeData,
		vector<Point2f>& codePose,
		BarCodeQuality* codeQuality = nullptr
	);

	/** @overload */
	virtual bool detectBest(const Mat& img, const vector<Point2f>& roi,
		BarCodeType& codeType,
		std::string& codeData,
		vector<Point2f>& codePose,
		BarCodeQuality* codeQuality = nullptr
	);

	/*! Detect multiple barcodes in the given image
	* @param img input image for detection
	* @param codeTypes output the result code types
	* @param codeDatas output the result codes
	* @param codePoses output the poses of barcodes
	* @param maxCount expect maximum count of the found barcodes
	* @param sortBy how the result should be sorted, default to no sort
	* @param mask input mask for exclude some pixel from detection
	* @return count of the found barcodes
	*/
	virtual int detectMulti(const Mat& img,
		vector<BarCodeType>& codeTypes,
		vector<std::string>& codeDatas,
		vector<vector<Point2f> >& codePoses,
		int maxCount,
		SortBy sortBy = SortBy::None
	);
	/** @overload */
	virtual int detectMulti(const Mat& img, const vector<Point2f>& roi,
		vector<BarCodeType>& codeTypes,
		vector<std::string>& codeDatas,
		vector<vector<Point2f> >& codePoses,
		int maxCount,
		SortBy sortBy = SortBy::None
	);

	private:
	void genBarCodeParamPack(BarCodeParamPack& pack);
};

#endif // BarCodeDetector_h_