#
# README / KOCR
#

 * 説明

 簡易OCRエンジンです。手書き文字を認識することが出来ます。内部では、
 あらかじめ登録された手書き文字データベースとの類似画像検索を行い、
 もっとも類似する文字のクラスを返すことで、文字読み取りを行います。
 再学習は容易で、さまざまな用途に対応できます。また、オープンソース
 形式で開発されており、自由に利用が可能です。

 なお、複数文字の認識も可能です。

 また、コンパイル時のオプションで、認識アルゴリズムをCNN、SVM、最近傍法
 で切り替えることが可能です。なお、最近傍法のデータベースファイルは、
 拡張子.dbですが、SVM法は拡張子.xmlとなっています。下記は、適宜、読み
 替えてご利用下さい。


 * インストール

 まず、OpenCVをインストールして下さい。linuxであれば、下記を実行すると
 良いはずです。

# apt-get install libcv-dev
# apt-get install libhighgui-dev
# apt-get install libcvaux-dev

 そのうえで、srcディレクトリでmakeして下さい。SOLVER=CNNを指定するか
 何も指定しないとCNNバージョンがコンパイルされます。

$ cd src
$ make

 make時にSOLVER=SVMを指定するとSVMバージョンでコンパイルされます

$ make SOLVER=SVM

 SOLVERにCNN, SVM以外の文字を指定すると最近傍法版がコンパイルされます

$ make SOLVER=OTHER

 - システムへのインストール(/usr/local 以下にインストールされます)
$ make install

 - インストール先を変える場合
$ make install PREFIX=/usr


 * 使い方

[CNN]

 - 学習済みの重みファイルと読ませたい文字列を当てると、認識結果を返します

$ ./kocr ../databases/cnn-num.bin ../images/samples/sample-img-6.pbm

 - 重みファイルと画像リストファイルを与えると性能評価を行います(未実装)

$ ./kocr ../databases/cnn-num.bin ../images/faximg/list-num.txt

 学習及び重みファイルの作成についてはpythonを用いて行います(後述)

[SVM, 最近傍法]

 - 手書き文字のサンプルを学習させ、「データベースファイル」を作ります
 データベースファイルの拡張子はSVMなら.xml、最近傍法なら.dbとなります

$ ./kocr ../images/faximg/list-num.txt
3098 images found
extracting features...
extraction completed...
database file is generated: ../images/faximg/list-num.db
$

 - データベースファイルと読ませたい文字画像を与えると、結果を返します

$ ./kocr ../images/faximg/list-num.db ../images/samples/sample-img-6.pbm
loading database file: ../images/faximg/list-num.db
../images/samples/sample-img-6.pbm
Recogized: 6 (1007.498883)
$

 - データベースとアルゴリズムの性能評価を行うことも出来ます

$ ./kocr ../images/faximg/list-num.db
loading database file, ../images/faximg/list-num.db...
starting leave-one-out testing...
Recog-rate = 0.991285 (= 3071 / 3098 )
$


 * 画像リストファイル

画像リストファイルは、2種類のフォーマットに対応しています。

i) 画像ファイル名とクラス名をスペース区切りにする (gocr形式)

$ cat db.lst
db_0031_4b8dd78b.pbm 1
db_0032_4b8dd78c.pbm 2
db_0033_4b8dd78c.pbm 3
db_0034_4b8dd78d.pbm 4
db_0035_4b8dd78d.pbm 5

ii) ファイル名の先頭にクラス名を埋める (kocr形式)

$ cat list-num.lst
0-001-20100420090002-blockImg-close_aftercare.png
0-001-20100513090002-blockImg-close_aftercare.png
0-001-20100513090002-blockImg-perception_female.png
0-001-20100513090002-blockImg-perception_male.png
0-001-20100514085002-blockImg-perception_female.png

いずれの場合も、.db拡張子の付いたデータベースファイルを作成します。


 * 学習及び重みファイルの作成について
 pythonのDeep Learning用ライブラリKerasを用いて学習を行います。

 詳しくはlearningフォルダのREADME.mdをご覧ください。


 * ファイル一覧

 README		このファイル

 src/		ソースディレクトリ
    /Makefile	Makefile
    /main.cpp	main
    /kocr.cpp	OCRエンジン本体
    /kocr.h	OCR用ヘッダ
    /subr.cpp	画像処理サブルーチン
    /subr.h	画像処理サブルーチン用ヘッダ
    /Labeling.h	画像処理サブルーチン用ヘッダ
    /cropnums.cpp 文字切り出しルーチン
    /cropnums.h 文字切り出しルーチン用ヘッダ
    /kocr_cnn.cpp CNN利用時のエンジン本体
    /kocr_cnn.h CNN利用時のOCR用ヘッダ
    /forward_cnn.h CNNの認識部

 images/	文字画像ディレクトリ

       /erroneous 読み取り困難画像例
       /numbers 手書き0～9
       /09db	手書き0～9
       /mbsdb	手書○×△
       /mbscdb	手書○×△✓
       /iddb
       /idocrdb
       /sample-ocrb	OCRBフォントファックスデータ
       /sample-sf
       /numocrb	/numbers と /sample-ocrb をマージしたもの

       /error	システムのエラー出力用
       /samples	読み取りテスト用サンプルファイル


 * 外部API

[CNN]

 Network *kocr_cnn_init(char *filename);
 	kocr利用開始。重みファイル(filename)を読み込んだCNN返す。

 char *kocr_recognize_image(Network *net, char *filename);
 	画像ファイルを認識する。返値は認識した文字列。

 void kocr_cnn_finish(Network *);
 	kocr利用終了。CNNが確保しているメモリを解放する。

[SVM]

 CvSVM *kocr_init(char *filename);
 	kocr利用開始。学習済みのSVMを返す。

 char *kocr_recognize_image(CvSVM *db, char *fname);
 	画像ファイルを認識する。返値は認識した文字列。

 void kocr_finish(CvSVM *db);
 	kocr利用終了。SVMを解放する。

[最近傍法]

feature_db *kocr_init(char *filename);
	kocr利用開始。db_load()した結果を返す。
	今のところ実体はdb_load()しているだけ。

char *kocr_recognize_image(feature_db * db, char *fname);
	画像ファイルを認識する。返値は認識した文字列。

void kocr_finish(feature_db *db);
	kocr利用終了。DBを解放する。