程序说明

如无另外说明，python程序均要求使用Python3。

识别部分

数据

预训练数据集

对应程序为classifier/utils/gnt.py
使用的数据集为CASIA-HWDB offline 1.0-1.2。
程序需要指定的参数如下：

1. data_dir:数据集图像所在文件夹路径
2. number_file:含有数据集中当前部分（训练、测试）对应的gnt文件列表的txt文件所在路径
3. image_dir:输出单子样本图片保存的文件夹路径
4. label_dir：输出单子样本标注txt文件保存的文件夹路径

古籍数据集

对应程序为classifier/utils/difangzhi.py
唯一需要指定的参数为root_dir，为地方志数据集所在文件夹的路径，其中应包含4505, 4520等等一系列文件夹。
程序会自动在root_dir中创建out文件夹，其中train,test两个文件夹下分别保存了用于训练和测试的古籍单字样本，out目录下还直接保存了500张地方志文档图像，这部分图像在后续定位部分会用到。

生成单字样本

对应程序为classifier/utils/gen_printed_char.py
需要指定的参数如下：

1. out_dir:生成的样本保存的目录
2. font_dir:使用的字体所在的目录路径，其中包含所有用到的字体
3. char:需要生成的汉字字符
4. w:生成的字符图像的宽度
5. w:生成的字符图像的高度

训练与测试

预训练

对应程序为classifier/casia_train.py
训练开始前需要修改代码65和68行的数据集路径，使其分别指向数据中预训练数据集的训练、测试文件夹路径。
程序会自动创建文件夹output/pretrain（如果不存在），并将模型保存在其中。

正式训练

对应程序为classifier/difangzhi_train.py
训练开始前需要修改代码69和72行的数据集路径，使其分别指向数据中古籍数据集的训练、测试文件夹路径。
程序会自动创建文件夹output（如果不存在），并将模型保存在其中。

测试

无论是预训练，还是正式训练，训练的脚本文件中都已经包含了测试的部分，当在测试集上的准确率高过一定阈值后，程序将会保存模型到相应文件夹。

定位部分

图像应为png或者jpg格式。
程序运行时顺序为：

1. 预处理
2. 进行连通域分析（仅基于深度学习的定位方法需要）
3. 字符定位

预处理

对应程序为locator/preprocess.py。

数据准备

将原始图片和其对应的ground truth标注txt放于同一文件夹下，其中图片和标注的文件名一一对应，如：

sourcedir/xxx.jpg -- 图片名为xxx
sourcedir/xxx.txt -- 标注txt名同样为xxx

如果已经运行过识别部分提到的classifer/utils/difangzhi.py，那么source_dir设置为out的路径即可。

参数

唯一需要指定的参数是img_dir，它是图片和标注所在文件夹，请使用绝对路径，并在路径最后加上/，如：

python preprocess.py -img_dir /data/source_dir/

输出

程序会产生两个文件夹，分别为bw_out，和color_out。其中bw_out是进行了完整的预处理后结果，color_out则是只进行了边界移除。
两个文件夹中的内容均为图像及其对应的经过处理的标注文件（进行边界移除后需要改变标注的位置）。
bw_out中的内容是后续定位算法的输入。
color_out中的内容是连通域分析的输入（因为连通域分析要求输入图像不能为二值图像）。
训练集、测试集、验证集需要分别运行，并将各自的结果拷贝到其他目录，否则下一次运行时会覆盖上一次的结果。

连通域分析（可选）

对应程序为locator/dtp.py。

参数

有两个参数需要设置：

1. image_dir，将其设置为预处理得到的color_out所在位置，请使用绝对路径。
2. out_dir，输出文件夹，请使用绝对路径，并在结尾加上/。
   运行示例：

python dtp.py -image_dir /data1/color_out -out_dir /data1/out/

输出

程序会在指定的输出路径创建一个image文件夹，里面是连通域分析得到的可视化结果。在输出路径的根目录下则会创建后缀名为.npz的文件，
为连通域分析得到的结果，会作为后续算法的输入。

说明

连通域分析算法比较慢，单张图像大约需要30s左右，目前程序使用了多个线程并行处理，但是图像数目很多时仍然需要较长时间。

基于投影的字符定位算法

对应locator/OCR文件夹下程序。

依赖

• OpenCV >= 3.4
• Cmake >= 3.3

参数

将test.sh中/mnt/c/Users/Deng/Desktop/bw_out/.jpg中.jpg前的部分改为预处理得到的bw_out路径，请使用绝对路径。

编译

进入OCR目录后

1. mkdir build && cd build
2. cmake .. && make

运行

在build目录下

1. cp ../test.sh ./
2. mkdir res_img res_txt
3. ./test.sh （运行前请确保有执行权限）

输出

res_img中会保存字符定位的可视化结果，res_txt是检测得到的对应的.txt标注文件。

测试

对应程序为locator/OCR/evaluate_box.py。
需要制定的参数为，检测得到的字符区域文本文件所在文件夹路径，ground truth文本文件所在文件夹路径以及IOU阈值。
文件夹中每一个文本文件对应一张图片，且两个文件夹中文件的名称应该一一对应。

基于深度学习的字符定位算法

依赖

• Pytorch >= 0.4.1
• 其它基本Anaconda都自带了，如果提示缺少包，使用conda安装即可。

数据准备

1. 在rcnn目录下创建dataset/train，datast/val，dataset/test以及npz/train, npz/test, npz/val目录。
2. 分别复制数据到rcnn/dataset/train等。注意，训练和验证集必须与bw_out中格式一致，即图片和标注一一对应。测试集则只需要图片。拷贝时命令格式如下：

   cp xxx/bw_out/* xxx/rcnn/dataset/train/

3. 复制连通域分析结果到rcnn/npz相应的目录下（训练、验证、测试集都需要），如：

   cp xxx/train_dtp/*.npz xxx/rcnn/npz/train/

参数

大部分参数都使用默认参数即可，有几个重要的参数说明如下：

1. image_size：网络输入的大小，设置过大会导致显存溢出，推荐设置为900。
2. dtp_train：值为1，使用连通域分析结果训练，值为0，则不使用。推荐使用，默认为1。
3. pretrained：是否加载已经训练好的模型的权重。在继续训练时需要声明。
4. model_path：训练好的模型的路径，如果声明了pretrained，那么必须提供有效的model_path参数。
5. eval_every：训练时多少次迭代进行一次验证，不要设置的过小，否则模型预测的结果中反例过多，采样时会出现随机的结果，默认为200。
6. max_iters：训练时最大迭代次数，默认为10000。
7. out_path：训练时保存验证集上结果的目录，默认为./out。

训练

对应程序locator/rcnn/train.py。
开始训练之前需要修改第23行的trainset以及第26行的testset中的数据集路径，将其设置为dataset文件夹下相应文件夹即可，
结尾需要加/。
第一次加载数据集时会生成h5和json文件，会比较慢，但再次加载数据时会比较快。请确保此时rcnn/npz文件夹下有对应的.npz文件。
如果没有验证集，那么将valset的数据集路径设为和trainset一样即可，并修改eval_every，使其大于max_iters即可。
运行示例：

python train.py -image_size 900 -- 除image_size均使用默认参数
python train.py -image_size 900 -eval_every 20000 -- 不验证

测试

对应程序locator/rcnn/inference.py。
同样，需要修改第23行testset中数据集的路径为rcnn/dataset下对应的文件夹，结尾需要加/。
运行示例：

python inference.py -image_size 900 -model_path ./checkpoints/rcnn/rcnn_0.91_0.83.pth.tar

输出

训练

训练时程序会创建log文件夹，其中保存了在验证集上，不同IOU阈值下的召回率和准确率。
训练时还会将验证集的中间结果保存在自动创建的out文件夹下（可能有检测不到字符的情况）。out根目录下会有检测到的字符位置坐标文件，out/image则是对应的可视化结果。
满足召回率、准确率均在80%以上的网络参数会保存在自动创建的checkpoints/rcnn文件夹下，文件名为训练开始时间与召回率、准确率的拼接。

测试

测试时程序会创建test_out文件夹，其根目录中保存了检测到的字符的坐标文件，test_out/vis中则保存了可视化结果。

系统整体测试

对古籍文档图像进行字符定位并识别后，可以对系统整体进行测试。

创建数据库文件

对应程序为make_database.py
批量测试前，需要先创建数据库文件。
需要指定的参数如下：

1. db_path:数据库文件保存的路径
2. img_dir:指向数据准备中输出的bw_out所在的路径
3. ocr_dir:基于投影的字符定位算法输出的txt文本文件所在文件夹路径
4. ocr_out_dir:基于投影的字符定位算法的结果中加入类别信息后保存的文件夹路径
5. rcnn_dir:基于深度学习的字符定位算法输出的txt文本文件所在文件夹路径
6. rcnn_out_dir:基于深度学习的字符定位算法的结果中加入类别信息后保存的文件夹路径
7. gt_dir:ground truth的txt文本文件所在文件夹路径

程序会生成.db数据库文件，并向定位的结果中加入当前字符类别、下一个字符类别、下下个字符类别信息，之后将其保存到指定目录。
数据库文件中会有3张表，表名分别为OCR, RCNN, GT, 分别对应基于投影的字符定位算法、基于深度学习的字符定位算法和ground truth。

测试

对应程序为system_test.py文件。
系统支持两种查询方式，分别介绍：

1. 通过字符串查询(query by string)
   此时将method参数设置为qbs，同时将words参数设置为要检索的关键词。
   可能需要修改的参数如下：
   1. 73行，数据库文件的路径
   2. 109行，在哪一个表中检索，默认为RCNN
2. 通过示例查询(query by example)
   此时将method参数设置为qbe，同时需要通过image_path参数指定关键词中各字符所对应的示例图片路径
   可能需要修改的参数如下：
   1. 73行，数据库文件的路径
   2. 90行，用于将示例图片转化为相应标签的分类器的模型路径
   3. 109行，在哪一个表中检索，默认为RCNN

查询示例：

python system_test.py -method qbe -image_path ./querys/kongzi/1.jpg ./querys/kongzi/2.jpg

程序会输出查询当前关键词计算得到的AP值。