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