diff -r 666f914201fb -r 2fe1408b6811 epoc32/include/mw/ocrsrv.h --- a/epoc32/include/mw/ocrsrv.h Tue Nov 24 13:55:44 2009 +0000 +++ b/epoc32/include/mw/ocrsrv.h Tue Mar 16 16:12:26 2010 +0000 @@ -1,1 +1,469 @@ -ocrsrv.h +/* +* Copyright (c) 2002-2005 Nokia Corporation and/or its subsidiary(-ies). +* All rights reserved. +* This component and the accompanying materials are made available +* under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members +* which accompanies this distribution, and is available +* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". +* +* Initial Contributors: +* Nokia Corporation - initial contribution. +* +* Contributors: +* +* Description: APIs of the OCR(Optical Character Recognition), current engine +* can recognize 24 bit colored image and 8 bit gray scale image +* in BMP format.And the size of images are also limited within +* 1600x1200 in pixel +* +* +*/ + + +#ifndef OCRSRV_H +#define OCRSRV_H + +// INCLUDE FILES +#include + +// Constants + +//class declaration +class OCREngineFactory; + +/** + * OCR (Optical Character Recognition) Engine Observer + * + * This set of interfaces defines the observers of the OCR engine. This is the unique set + * for all types of engines. User needs to implement a concrete class which is derived from + * this class. + * + * @lib ocrsrv.lib + * @since S60 3.1 + */ +class MOCREngineObserver + { + public: + /** + * This interface will be called after the Block Recognition is completed. This calling + * only valid when using the EEngineRecognizeBlock type of engine + * @see OCREngineFactory::TEngineType + * @see MOCREngineRecognizeBlock + * + * @since S60 3.1 + * @param aError Error code to indicate the completion status + * @param aBlocks Pointer to the text information of the recognized image block, Please note + that the memory ownership belongs to the OCR engine and will not be passed + to your procedure after this calling + * @param aBlockCount Number of block identified + * @return None + */ + virtual void RecognizeBlockComplete(TInt aError, + const TOCRTextRgnInfo* aBlocks, + const TInt aBlockCount) = 0; + + /** + * This interface will be called after the Special Region Recognition is completed. This calling + * only valid when using the EEngineRecognizeBlock type of engine + * @see OCREngineFactory::TEngineType + * @see MOCREngineRecognizeBlock + * + * @since S60 3.1 + * @param aError Error code to indicate the completion status + * @param aBlocks Pointer to the text information of the recognized image block, Please note + that the memory ownership belongs to the OCR engine and will not be passed + to your procedure after this calling + * @param aBlockCount Number of block identified + * @return None + */ + virtual void RecognizeSpecialRegionComplete(TInt aError, + const TOCRTextRgnInfo* aBlocks, + const TInt aBlockCount) = 0; + + /** + * This interface will be called after the Full Image Recognition is completed. This calling + * only valid when using the EEngineLayoutRecognize type of engine + * @see OCREngineFactory::TEngineType + * @see MOCREngineLayoutRecognize + * + * @since S60 3.1 + * @param aError Error code to indicate the completion status + * @param aBlocks Pointer to the text information of the recognized image block, Please note + that the memory ownership belongs to the OCR engine and will not be passed + to your procedure after this calling + * @param aBlockCount Number of block identified + * @return None + */ + virtual void RecognizeComplete(TInt aError, + const TOCRTextRgnInfo* aBlocks, + const TInt aBlockCount) = 0; + + /** + * This interface will be called after the Full Image Layout Analysis is completed. This calling + * only valid when using the EEngineLayoutRecognize type of engine + * @see OCREngineFactory::TEngineType + * @see MOCREngineLayoutRecognize + * + * @since S60 3.1 + * @param aError Error code to indicate the completion status + * @param aBlocks Pointer to the text information of the recognized image block, Please note + that the memory ownership belongs to the OCR engine and will not be passed + to your procedure after this calling + * @param aBlockCount Number of block identified + * @return None + */ + virtual void LayoutComplete(TInt aError, + const TOCRBlockInfo* aBlocks, + const TInt aBlockCount) = 0; + + /** + * This interface will be called during the procession and indicates the progress. + * + * @since S60 3.1 + * @param aPercent A percentage of the current progression + * @return None + */ + virtual void RecognizeProcess(const TUint aPercent) = 0; + }; + + +/** + * OCR (Optical Character Recognition) Engine Base + * + * Base class of the OCR engine, this offers definitions of the features which + * all engines shall give support + * + * @lib ocrsrv.lib + * @since S60 3.1 + */ +class MOCREngineBase + { + public: + + /** + * Get the current version of the OCR interfaces + * + * @since S60 3.1 + * @return Current version + */ + virtual TVersion GetVersion() const = 0; + + /** + * This interface refreshes the installed language packages. The OCR engine + * supports the languages to be installed as SIS packages and can be installed + * or uninstalled dynamically. This method shall be called after changes made + * on the installed language packages + * + * @leave KErrNotFound No OCR engine found + * @since S60 3.1 + * @return None + */ + virtual void RefreshInstalledLanguageL() = 0; + + /** + * This method sets the languages for the recognition, maximum 2 languages can + * be passed together, regardless of their position in the array + * + * @since S60 3.1 + * @param aActiveLanguage Array of specified languages @see GetInstalledLanguage + * @return None + * + * @leave KErrArgument Language count is more than two + * @leave KErrNotSupported The language is not supported by current OCR engine + * @leave KErrOcrBadLanguage Unsupported language + * @leave KErrOcrBadDictFile Not set any language packages + */ + virtual void SetActiveLanguageL(const RArray& aActiveLanguage) = 0; + + /** + * This method gets the languages which are currently installed and supported + * + * @since S60 3.1 + * @param aLanguages Array of installed languages @see SetActiveLanguageL + * @return None + */ + virtual void GetInstalledLanguage(RArray& aLanguages) const = 0; + + /** + * This method cancels the recognition + * Call to this method the process will be terminated, and a KErrCancel flag + * will be passed to MOCREngineObserver's observers and through the aError + * parameter. Call this method when the engine is not working will not take + * any effect, this method internally calls IsEngineActive method + * @see MOCREngineObserver + * + * @since S60 3.1 + * @return None + */ + virtual void CancelOperation() = 0; + + /** + * This method judges whether a language is supported + * + * @since S60 3.1 + * @param aLanguage A language specifed + * @return ETrue if supported; EFalse otherwise + */ + virtual TBool IsLanguageSupported(const TLanguage aLanguage) = 0; + + /** + * This method tests whether the engine is working or not + * Typically you could call this method to test whether there is + * an outstanding request or not. + * Note that when you are trying to exit the application when + * there's an outstanding issue, you should first call this method + * and call CancelOperation method before really terminate the + * client application + * + * @since S60 3.1 + * @return ETrue if the engine is working; EFalse otherwise + */ + virtual TBool IsEngineActive() const = 0; + }; + + +/** + * OCR (Optical Character Recognition) Engine Interface Base + * + * Base interfaces for the OCR engine, all engines derived from this class + * User can access base features from Base method + * + * @lib ocrsrv.lib + * @since S60 3.1 + */ +class MOCREngineInterface + { + public: + + /** + * This method gets the MOCREngineBase interface, user can access base features + * from this method + * + * @since S60 3.1 + * @return Pointer to the engine base @see MOCREngineBase + */ + virtual MOCREngineBase* Base() const = 0; + + /** + * Virtual destructor + */ + virtual ~MOCREngineInterface() { }; + }; + + +/** + * OCR (Optical Character Recognition) Engine Interfaces with Layout Analysis + * + * This set of interfaces offers the OCR engine which supports Layout Analysis + * on full images. User shall pass the handle of the image through LayoutAnalysisL + * first, and then pass block ids to RecognizeL to complete the recognition. + * + * For Example: + * After passing the image handle to LayoutAnalysisL, the MOCREngineObserver::LayoutComplete + * will be called after the process. Then through the TOCRBlockInfo array (const TOCRBlockInfo* aBlock + * and const TInt aBlockCount), the user knows how many blocks have been identified + * together with their position information. Those blocks are marked with ids from Zero to + * aBlockCount - 1. + * + * Then the user must specify which blocks are going to be further processed (Note that layout analysis + * only gets you the position of those blocks, but does not recognize the characters inside each block). + * The const RArray& aBlock in MOCREngineLayoutRecognize::RecognizeL saves all the ids that are + * selected to be further processed. e.g. if you have 10 blocks from LayoutComplete, you can append + * 1, 3, 5, 7 to the TInt array and pass it to RecognizeL + * + * Note that this class shall be used together with TEngineType set to EEngineLayoutRecognize + * + * @lib ocrsrv.lib + * @since S60 3.1 + */ +class MOCREngineLayoutRecognize : public MOCREngineInterface + { + public: + + /** + * This method does the layout analysis for the full image + * + * @since S60 3.1 + * @param aBitmapHandle Handle of the image(get from CFbsBitmap::Handle()) + * @param aSettings Settings for layout analysis @see TOCRLayoutSetting + * @return None + * + * @leave KErrNotSupported Image shall be in BMP format (24bit colored or 8 bit grayscale) + * and the size shall not exceed 1600x1200 in pixel + * @leave KErrNotReady Internal object is not constructed + * @leave KErrAbort Child thread does not exist or operation is aborted + * @leave KErrServerBusy OCR service is busy + */ + virtual void LayoutAnalysisL(const TInt aBitmapHandle, + const TOCRLayoutSetting aSettings) = 0; + + /** + * This method does the character recognition for the image on base of the result from + * LayoutAnalysisL + * + * @since S60 3.1 + * @param aSettings Settings for recognition + * @param aBlockIdsToRecognize Block Ids to be recognized + * @return None + * + * @leave KErrNotReady Internal object is not constructed + * @leave KErrAbort Child thread does not exist or operation is aborted + * @leave KErrArgument Bolck information is available + * + */ + virtual void RecognizeL(const TOCRRecognizeSetting aSettings, + const RArray& aBlockIdsToRecognize) = 0; + }; + +/** + * OCR (Optical Character Recognition) Engine Interfaces without Layout Analysis + * + * This set of interfaces offers the OCR engine which does not support Layout Analysis + * on full images. User shall implement their own layout solution + * + * RecognizeBlockL recognizes text information in a single block area regardless of content + * + * RecognizeSpecialRegionL recognizes text information in a single block area and its content + * sensitive. User can select three different types of contents: e-mail address, phone numbers + * or web addresses @see TRegionInfo + * + * Note that this class shall be used together with TEngineType set to EEngineRecognizeBlock + * + * @lib ocrsrv.lib + * @since S60 3.1 + */ +class MOCREngineRecognizeBlock : public MOCREngineInterface + { + public: + + /** + * This method recognizes text in a single block + * + * @since S60 3.1 + * @param aBitmapHandle Handle of the image(get from CFbsBitmap::Handle()) + * @param aLayoutInfo Block information + * @return None + * + * @leave KErrNotSupported Image shall be in BMP format (24bit colored or 8 bit grayscale) + * and the size shall not exceed 1600x1200 in pixel + * @leave KErrNotReady Internal object is not constructed + * @leave KErrAbort Child thread does not exist or operation is aborted + * @leave KErrCouldNotConnect No connection to the font and bitmap server could be made + * @leave KErrUnknown No bitmap could be found with the specified handle number + * @leave KErrArgument aRegionInfo is available + * @leave KErrServerBusy OCR service is busy + */ + virtual void RecognizeBlockL(const TInt aBitmapHandle, + const TOCRLayoutBlockInfo aLayoutInfo) = 0; + + /** + * This method recognizes text with special content in a single block + * + * Note that SetActiveLanguageL has to be called first and language must be set to TLanguage::ELangEnglish + * + * @since S60 3.1 + * @param aBitmapHandle Handle of the image(get from CFbsBitmap::Handle()) + * @param aRegionInfo Block information + * @return None + * + * @leave KErrNotSupported Image shall be in BMP format (24bit colored or 8 bit grayscale) + * and the size shall not exceed 1600x1200 in pixel + * @leave KErrNotReady Internal object is not constructed + * @leave KErrAbort Child thread does not exist or operation is aborted + * @leave KErrCouldNotConnect No connection to the font and bitmap server could be made + * @leave KErrUnknown No bitmap could be found with the specified handle number + * @leave KErrArgument aRegionInfo is available + * @leave KErrServerBusy OCR service is busy + */ + virtual void RecognizeSpecialRegionL(const TInt aBitmapHandle, + const TRegionInfo aRegionInfo) = 0; + }; + +/** + * OCR (Optical Character Recognition) API + * + * This static class offers the OCR APIs. The user shall call CreateOCREngineL + * and get the instance of one type of the OCR engine and then convert the instance + * from MOCREngineInterface to MOCREngineLayoutRecognize or MOCREngineRecognizeBlock + * according to the type information. And use ReleaseOCREngine to destroy the engine. + * @see OCREngineFactory::TEngineType + * + * Note: This procedure will create a new thread in your current process in order to + * run the OCR APIs, so you don't need to create new threads for OCR by yourself + * + * For example: + * A typical usage for the factory class would be like: + * @code + * const TOcrEngineEnv env; + * env.iPriority = EPriorityLess; + * env.iMaxHeapSize = 1200*KMinHeapGrowBy; + * MOCREngineInterface* myEngine = CreateOCREngineL( aObserver, env, EEngineLayoutRecognize); + * MOCREngineLayoutRecognize* layoutEngine = STATIC_CAST( MOCREngineLayoutRecognize*, myEngine ); + * // TODO: call coresponding methods in layoutEngine + * ReleaseOCREngine( layoutEngine ); + * @endcode + * @lib ocrsrv.lib + * @since S60 3.1 + */ +class OCREngineFactory + { + public: + /** + * OCR Engine Types + */ + enum TEngineType + { + /** + * OCR Engine with layout analysis feature: + * by selecting this type of engine, LayoutAnalysisL + * shall be called first before RecognizeL. + */ + EEngineLayoutRecognize, + + /** + * Engine without layout analysis feature: + * Layout information shall be passed through TOCRLayoutBlockInfo + * or TRegionInfo to the interfaces + */ + EEngineRecognizeBlock + + }; + + public: + + /** + * Create the OCR engine instance + * + * @since S60 3.1 + * @param aObserver Pointer to the call callback function + * @param aEngineEnv Engine environment settings @see TOcrEngineEnv + * @param aEngineType Select a type of engine to be created @see OCREngineFactory::TEngineType + * @return Pointer to the engine created @see MOCREngineInterface + * + * @leave KErrArgument aEngineEnv.iMaxHeapSize is lower(equal) than KMinHeapGrowBy*1000 + * @leave KErrNotSupported aEngineType is not supported + */ + IMPORT_C static MOCREngineInterface* CreateOCREngineL(MOCREngineObserver& aObserver, + const TOcrEngineEnv aEngineEnv, + TEngineType aEngineType); + + /** + * Release the OCR engine instance + * + * @since S60 3.1 + * @param aEng Pointer to the instance of the Engine + * @return None + */ + IMPORT_C static void ReleaseOCREngine(MOCREngineInterface* aEng); + + private: + + /** + * Constructor + */ + OCREngineFactory(); + }; + +#endif // OCRSRV_H + +// End of file