Package: cnstd
CnSTDUpdate 2023.10.09：发布 V1.2.3.5主要变更：支持基于环境变量CNSTD_DOWNLOAD_SOURCE的取值，来决定不同的模型下载路径，默认使用国内OSS地址。LayoutAnalyzer中增加了参数model_categories和model_arch_yaml，用于指定模型的类别名称列表和模型架构。...Update 2023.06.30：发布 V1.2.3主要变更：基于新标注的数据，重新训练了MFD YoloV7模型，目前新模型已部署到P2T网页版。具体说明见：Pix2Text (P2T) 新版公式检测模型 | Breezedeus.com。之前的 MFD YoloV7 模型已开放给星球会员下载，具体说明见：P2T YoloV7 数学公式检测模型开放给星球会员下载 | Breezedeus.com。增加了一些Label Studio相关的脚本，见scripts。如：利用 CnSTD 自带的 MFD 模型对目录中的图片进行公式检测后生成可导入到Label Studio中的JSON文件；以及，Label Studio标注后把导出的JSON文件转换成训练 MFD 模型所需的数据格式。注意，MFD 模型的训练代码在yolov7（devbranch）中。了解更多：RELEASE.md。CnSTD是Python 3下的场景文字检测（Scene Text Detection，简称STD）工具包，支持中文、英文等语言的文字检测，自带了多个训练好的检测模型，安装后即可直接使用。CnSTD自V1.2.1版本开始，加入了数学公式检测（Mathematical Formula Detection，简称MFD）模型，并提供训练好的模型可直接用于检测图片中包含的数学公式（行内公式embedding与独立行公式isolated）。欢迎扫码加入微信交流群：作者也维护知识星球CnOCR/CnSTD/P2T私享群，欢迎加入。知识星球私享群会陆续发布一些CnOCR/CnSTD/P2T相关的私有资料，包括更详细的训练教程，未公开的模型，使用过程中遇到的难题解答等。本群也会发布OCR/STD相关的最新研究资料。自V1.0.0版本开始，CnSTD从之前基于 MXNet 实现转为基于PyTorch实现。新模型的训练合并了ICPR MTWI 2018、ICDAR RCTW-17和ICDAR2019-LSVT三个数据集，包括了46447个训练样本，和1534个测试样本。相较于之前版本， 新版本的变化主要包括：加入了对PaddleOCR检测模型的支持；部分调整了检测结果中box的表达方式，统一为4个点的坐标值；修复了已知bugs。如需要识别文本框中的文字，可以结合OCR工具包cnocr一起使用。示例场景文字检测（STD）数学公式检测（MFD）MFD 模型检测图片中包含的数学公式，其中行内的公式检测为embedding类别，独立行的公式检测为isolated。模型训练使用了英文IBEM和中文CnMFD_Dataset两个数据集。版面分析（Layout Analysis）版面分析模型识别图片中的不同排版元素。模型训练使用的是CDLA数据集。可识别以下10中版面元素：正文标题图片图片标题表格表格标题页眉页脚注释公式TextTitleFigureFigure captionTableTable captionHeaderFooterReferenceEquation安装嗯，顺利的话很简单（bless）。pipinstallcnstd如果需要使用 ONNX 模型（model_backend=onnx），请使用以下命令安装：CPU环境使用 ONNX 模型：pipinstallcnstd[ort-cpu]GPU环境使用 ONNX 模型：pipinstallcnstd[ort-gpu]注意：如果当前环境已经安装了onnxruntime包，请先手动卸载（pip uninstall onnxruntime）后再运行上面的命令。安装速度慢的话，可以指定国内的安装源，如使用豆瓣源：pipinstallcnstd-ihttps://mirrors.aliyun.com/pypi/simple【注意】：请使用Python3(3.6以及之后版本应该都行)，没测过Python2下是否ok。依赖opencv，所以可能需要额外安装opencv。已有STD模型CnSTD 从V1.2开始，可直接使用的模型包含两类：1）CnSTD 自己训练的模型，通常会包含 PyTorch 和 ONNX 版本；2）从其他ocr引擎搬运过来的训练好的外部模型，ONNX化后用于 CnSTD 中。直接使用的模型都放在cnstd-cnocr-models项目中，可免费下载使用。1. CnSTD 自己训练的模型当前版本（SinceV1.1.0）的文字检测模型使用的是DBNet，相较于 V0.1 使用的PSENet模型， DBNet 的检测耗时几乎下降了一个量级，同时检测精度也得到了极大的提升。目前包含以下已训练好的模型：模型名称参数规模模型文件大小测试集精度（IoU）平均推断耗时（秒/张）下载方式db_resnet3422.5 M86 M0.73223.11自动db_resnet1812.3 M47 M0.72941.93自动db_mobilenet_v34.2 M16 M0.72691.76自动db_mobilenet_v3_small2.0 M7.9 M0.70541.24自动db_shufflenet_v24.7 M18 M0.72381.73自动db_shufflenet_v2_small3.0 M12 M0.71901.29自动db_shufflenet_v2_tiny1.9 M7.5 M0.71721.14下载链接上表耗时基于本地 Mac 获得，绝对值无太大参考价值，相对值可供参考。IoU的计算方式经过调整，仅相对值可供参考。相对于两个基于ResNet的模型，基于MobileNet和ShuffleNet的模型体积更小，速度更快，建议在轻量级场景使用。2. 外部模型以下模型是PaddleOCR中模型的ONNX版本，所以不会依赖PaddlePaddle相关工具包，故而也不支持基于这些模型在自己的领域数据上继续精调模型。这些模型支持检测竖排文字。model_namePyTorch 版本ONNX 版本支持检测的语言模型文件大小ch_PP-OCRv3_detX√简体中问、英文、数字2.3 Mch_PP-OCRv2_detX√简体中问、英文、数字2.2 Men_PP-OCRv3_detX√英文、数字2.3 M更多模型可参考PaddleOCR/models_list.md。如有其他外语（如日、韩等）检测需求，可在知识星球CnOCR/CnSTD私享群中向作者提出建议。使用方法首次使用CnSTD时，系统会自动下载zip格式的模型压缩文件，并存放于~/.cnstd目录（Windows下默认路径为C:\Users\<username>\AppData\Roaming\cnstd）。下载速度超快。下载后的zip文件代码会自动对其解压，然后把解压后的模型相关目录放于~/.cnstd/1.2目录中。如果系统无法自动成功下载zip文件，则需要手动从百度云盘（提取码为nstd）下载对应的zip文件并把它存放于~/.cnstd/1.2（Windows下为C:\Users\<username>\AppData\Roaming\cnstd\1.2）目录中。模型也可从cnstd-cnocr-models中下载。放置好zip文件后，后面的事代码就会自动执行了。场景文字检测（STD）使用类CnStd进行场景文字的检测。类CnStd的初始化函数如下：classCnStd(object):"""场景文字检测器（Scene Text Detection）。虽然名字中有个"Cn"（Chinese），但其实也可以轻松识别英文的。"""def__init__(self,model_name:str='ch_PP-OCRv3_det',*,auto_rotate_whole_image:bool=False,rotated_bbox:bool=True,context:str='cpu',model_fp:Optional[str]=None,model_backend:str='onnx',# ['pytorch', 'onnx']root:Union[str,Path]=data_dir(),use_angle_clf:bool=False,angle_clf_configs:Optional[dict]=None,**kwargs,):其中的几个参数含义如下：model_name:  模型名称，即前面模型表格第一列中的值。默认为ch_PP-OCRv3_det。auto_rotate_whole_image:  是否自动对整张图片进行旋转调整。默认为False。rotated_bbox:  是否支持检测带角度的文本框；默认为True，表示支持；取值为False时，只检测水平或垂直的文本。context：预测使用的机器资源，可取值为字符串cpu、gpu、cuda:0。model_fp:  如果不使用系统自带的模型，可以通过此参数直接指定所使用的模型文件（.ckpt文件）。model_backend(str): 'pytorch', or 'onnx'。表明预测时是使用 PyTorch 版本模型，还是使用 ONNX 版本模型。  同样的模型，ONNX 版本的预测速度一般是 PyTorch 版本的2倍左右。默认为onnx。root: 模型文件所在的根目录。Linux/Mac下默认值为~/.cnstd，表示模型文件所处文件夹类似~/.cnstd/1.2/db_shufflenet_v2_small。Windows下默认值为C:\Users\<username>\AppData\Roaming\cnstd。use_angle_clf(bool): 对于检测出的文本框，是否使用角度分类模型进行调整（检测出的文本框可能会存在倒转180度的情况）。默认为Falseangle_clf_configs(dict): 角度分类模型对应的参数取值，主要包含以下值：model_name: 模型名称。默认为 'ch_ppocr_mobile_v2.0_cls'model_fp: 如果不使用系统自带的模型，可以通过此参数直接指定所使用的模型文件（'.onnx' 文件）。默认为None。具体可参考类AngleClassifier的说明每个参数都有默认取值，所以可以不传入任何参数值进行初始化：std = CnStd()。文本检测使用类CnOcr的函数detect()，以下是详细说明：类函数CnStd.detect()defdetect(self,img_list:Union[str,Path,Image.Image,np.ndarray,List[Union[str,Path,Image.Image,np.ndarray]],],resized_shape:Union[int,Tuple[int,int]]=(768,768),preserve_aspect_ratio:bool=True,min_box_size:int=8,box_score_thresh:float=0.3,batch_size:int=20,**kwargs,)->Union[Dict[str,Any],List[Dict[str,Any]]]:函数说明：函数输入参数包括：img_list: 支持对单个图片或者多个图片（列表）的检测。每个值可以是图片路径，或者已经读取进来PIL.Image.Image或np.ndarray,  格式应该是RGB3 通道，shape:(height, width, 3), 取值范围：[0, 255]。resized_shape:intortuple,tuple含义为(height, width),int则表示高宽都为此值；检测前，先把原始图片resize到接近此大小（只是接近，未必相等）。默认为(768, 768)。Note（注意）这个取值对检测结果的影响较大，可以针对自己的应用多尝试几组值，再选出最优值。例如(512, 768),(768, 768),(768, 1024)等。preserve_aspect_ratio: 对原始图片 resize 时是否保持高宽比不变。默认为True。min_box_size: 过滤掉高度或者宽度小于此值的文本框。默认为8，也即高或者宽小于8的文本框会被过滤去掉。box_score_thresh: 过滤掉得分低于此值的文本框。默认为0.3。batch_size: 待处理图片很多时，需要分批处理，每批图片的数量由此参数指定。默认为20。kwargs: 保留参数，目前未被使用。函数输出类型为list，其中每个元素是一个字典，对应一张图片的检测结果。字典中包含以下keys：rotated_angle:float, 整张图片旋转的角度。只有auto_rotate_whole_image==True才可能非0。detected_texts:list, 每个元素存储了检测出的一个框的信息，使用词典记录，包括以下几个值：box：检测出的文字对应的矩形框；np.ndarray, shape:(4, 2)，对应 box 4个点的坐标值(x, y);score：得分；float类型；分数越高表示越可靠；croppped_img：对应 "box" 中的图片patch（RGB格式），会把倾斜的图片旋转为水平。np.ndarray类型，shape: (height, width, 3),  取值范围：[0, 255]；示例:[{'box':array([[416,77],[486,13],[800,325],[730,390]],dtype=int32),'score':1.0,'cropped_img':array([[[25,20,24],[26,21,25],[25,20,24],...,[11,11,13],[11,11,13],[11,11,13]]],dtype=uint8)},...]调用示例fromcnstdimportCnStdstd=CnStd()box_info_list=std.detect('examples/taobao.jpg')或：fromPILimportImagefromcnstdimportCnStdstd=CnStd()img_fp='examples/taobao.jpg'img=Image.open(img_fp)box_infos=std.detect(img)识别检测框中的文字（OCR）上面示例识别结果中"cropped_img"对应的值可以直接交由cnocr中的CnOcr进行文字识别。如上例可以结合CnOcr进行文字识别：fromcnstdimportCnStdfromcnocrimportCnOcrstd=CnStd()cn_ocr=CnOcr()box_infos=std.detect('examples/taobao.jpg')forbox_infoinbox_infos['detected_texts']:cropped_img=box_info['cropped_img']ocr_res=cn_ocr.ocr_for_single_line(cropped_img)print('ocr result:%s'%str(ocr_res))注：运行上面示例需要先安装cnocr：pipinstallcnocr数学公式检测（MFD）与 版面分析（Layout Analysis）数学公式检测（MFD）与 版面分析（Layout Analysis）都是检测图片中感兴趣的元素，它们使用的都是基于YOLOv7的检测架构，在CnSTD都来源于相同的类LayoutAnalyzer，差别只是训练模型使用的数据不同。这两个模型的训练代码在yolov7中（Forked fromWongKinYiu/yolov7，感谢原作者。）类LayoutAnalyzer的初始化函数如下：classLayoutAnalyzer(object):def__init__(self,model_name:str='mfd',# 'layout' or 'mfd'*,model_type:str='yolov7_tiny',# 当前支持 [`yolov7_tiny`, `yolov7`]'model_backend:str='pytorch',model_categories:Optional[List[str]]=None,model_fp:Optional[str]=None,model_arch_yaml:Optional[str]=None,root:Union[str,Path]=data_dir(),device:str='cpu',**kwargs,)其中的参数含义如下：model_name: 字符串类型，表示模型类型。可选值：'mfd' 表示数学公式检测；'layout' 表示版面分析。默认值：'mfd'model_type: 字符串类型，表示模型类型。当前支持 'yolov7_tiny' 和 'yolov7'；默认值：'yolov7_tiny'。'yolov7' 模型暂不开源，当前仅开放给星球会员下载，具体说明见：P2T YoloV7 数学公式检测模型开放给星球会员下载 | Breezedeus.com。model_backend: 字符串类型，表示backend。当前仅支持: 'pytorch'；默认值：'pytorch'model_categories: 模型的检测类别名称。默认值：None，表示基于model_name自动决定model_fp: 字符串类型，表示模型文件的路径。默认值：None，表示使用默认的文件路径model_arch_yaml: 架构文件路径，例如 'yolov7-mfd.yaml'；默认值为 None，表示将自动选择。root: 字符串或Path类型，表示模型文件所在的根目录。Linux/Mac下默认值为~/.cnstd，表示模型文件所处文件夹类似~/.cnstd/1.2/analysisWindows下默认值为C:/Users/<username>/AppData/Roaming/cnstd。device: 字符串类型，表示运行模型的设备，可选值：'cpu' 或 'gpu'；默认值：'cpu'**kwargs: 额外的参数。函数输出结果为一个list，其中每个元素表示识别出的版面中的一个元素，包含以下信息：type: 版面元素对应的类型；可选值来自：self.categories;box: 版面元素对应的矩形框；np.ndarray, shape: (4, 2)，对应 box 4个点的坐标值(x, y);score: 得分，越高表示越可信 。类函数LayoutAnalyzer.analyze()对指定图片（列表）进行版面分析。defanalyze(self,img_list:Union[str,Path,Image.Image,np.ndarray,List[Union[str,Path,Image.Image,np.ndarray]],],resized_shape:Union[int,Tuple[int,int]]=700,box_margin:int=2,conf_threshold:float=0.25,iou_threshold:float=0.45,)->Union[List[Dict[str,Any]],List[List[Dict[str,Any]]]]:函数说明：函数输入参数包括：img_list(str or list): 待识别图片或图片列表；如果是np.ndarray，则应该是shape为[H, W, 3]的 RGB 格式数组resized_shape(int or tuple): (H, W); 把图片resize到此大小再做分析；默认值为700box_margin(int): 对识别出的内容框往外扩展的像素大小；默认值为2conf_threshold(float): 分数阈值；默认值为0.25iou_threshold(float): IOU阈值；默认值为0.45**kwargs: 额外的参数。调用示例fromcnstdimportLayoutAnalyzerimg_fp='examples/mfd/zh5.jpg'analyzer=LayoutAnalyzer('mfd')out=analyzer.analyze(img_fp,resized_shape=700)print(out)脚本使用cnstd包含了几个命令行工具，安装cnstd后即可使用。STD 预测单个文件或文件夹中所有图片使用命令cnstd predict预测单个文件或文件夹中所有图片，以下是使用说明：(venv)➜cnstdgit:(master)✗cnstdpredict-h
Usage:cnstdpredict[OPTIONS]预测单个文件，或者指定目录下的所有图片

Options:-m,--model-name[ch_PP-OCRv2_det|ch_PP-OCRv3_det|db_mobilenet_v3|db_mobilenet_v3_small|db_resnet18|db_resnet34|db_shufflenet_v2|db_shufflenet_v2_small|db_shufflenet_v2_tiny|en_PP-OCRv3_det]模型名称。默认值为db_shufflenet_v2_small-b,--model-backend[pytorch|onnx]模型类型。默认值为`onnx`-p,--pretrained-model-fpTEXT使用训练好的模型。默认为`None`，表示使用系统自带的预训练模型-r,--rotated-bbox是否检测带角度（非水平和垂直）的文本框。默认为`True`--resized-shapeTEXT格式："height,width";预测时把图片resize到此大小再进行预测。两个值都需要是32的倍数。默认为`768,768`--box-score-threshFLOAT检测结果只保留分数大于此值的文本框。默认值为`0.3`--preserve-aspect-ratioBOOLEANresize时是否保留图片原始比例。默认值为`True`--contextTEXT使用cpu还是`gpu`运行代码，也可指定为特定gpu，如`cuda:0`。默认为`cpu`-i,--img-file-or-dirTEXT输入图片的文件路径或者指定的文件夹-o,--output-dirTEXT检测结果存放的文件夹。默认为`./predictions`-h,--helpShowthismessageandexit.例如可以使用以下命令对图片examples/taobao.jpg进行检测，并把检测结果存放在目录outputs中：cnstdpredict-iexamples/taobao.jpg-ooutputs具体使用也可参考文件Makefile。MFD or Layout Analysis 预测单个文件使用命令cnstd analyze获得单个文件的 MFD 或者 Layout Analysis 结果，以下是使用说明：(venv)➜cnstdgit:(master)✗cnstdanalyze-h
Usage:cnstdanalyze[OPTIONS]对给定图片进行MFD或者版面分析。

Options:-m,--model-nameTEXT模型类型。`mfd`表示数学公式检测，`layout`表示版面分析；默认为：`mfd`-t,--model-typeTEXT模型类型。当前支持[`yolov7_tiny`,`yolov7`]-b,--model-backend[pytorch|onnx]模型后端架构。当前仅支持`pytorch`-c,--model-categoriesTEXT模型的检测类别名称（","分割）。默认值：None，表示基于`model_name`自动决定-p,--model-fpTEXT使用训练好的模型。默认为`None`，表示使用系统自带的预训练模型-y,--model-arch-yamlTEXT模型的配置文件路径--deviceTEXTcudadevice,i.e.0or0,1,2,3orcpu-i,--img-fpTEXT待分析的图片路径或图片目录-o,--output-fpTEXT分析结果输出的图片路径。默认为`None`，会存储在当前文件夹，文件名称为输入文件名称前面增加`out-`；如输入文件名为`img.jpg`,输出文件名即为`out-img.jpg`；如果输入为目录，则此路径也应该是一个目录，会将输出文件存储在此目录下--resized-shapeINTEGER分析时把图片resize到此大小再进行。默认为`608`--conf-threshFLOATConfidenceThreshold。默认值为`0.25`--iou-threshFLOATIOUthresholdforNMS。默认值为`0.45`-h,--helpShowthismessageandexit.例如可以使用以下命令对图片examples/mfd/zh.jpg进行 MFD，并把检测结果存放在文件out-zh.jpg中：(venv)➜cnstdanalyze-mmfd--conf-thresh0.25--resized-shape800-iexamples/mfd/zh.jpg-oout-zh.jpg具体使用也可参考文件Makefile。模型训练使用命令cnstd train训练文本检测模型，以下是使用说明：(venv)➜cnstdgit:(master)✗cnstdtrain-h
Usage:cnstdtrain[OPTIONS]训练文本检测模型

Options:-m,--model-name[db_resnet50|db_resnet34|db_resnet18|db_mobilenet_v3|db_mobilenet_v3_small|db_shufflenet_v2|db_shufflenet_v2_small|db_shufflenet_v2_tiny]模型名称。默认值为`db_shufflenet_v2_small`-i,--index-dirTEXT索引文件所在的文件夹，会读取文件夹中的`train.tsv`和`dev.tsv`文件[required]--train-config-fpTEXT训练使用的json配置文件[required]-r,--resume-from-checkpointTEXT恢复此前中断的训练状态，继续训练-p,--pretrained-model-fpTEXT导入的训练好的模型，作为初始模型。优先级低于"--restore-training-fp"，当传入"--restore-training-fp"时，此传入失效-h,--helpShowthismessageandexit.具体使用可参考文件Makefile。模型转存训练好的模型会存储训练状态，使用命令cnstd resave去掉与预测无关的数据，降低模型大小。(venv)➜cnstdgit:(master)✗cnstdresave-h
Usage:cnstdresave[OPTIONS]训练好的模型会存储训练状态，使用此命令去掉预测时无关的数据，降低模型大小

Options:-i,--input-model-fpTEXT输入的模型文件路径[required]-o,--output-model-fpTEXT输出的模型文件路径[required]-h,--helpShowthismessageandexit.未来工作进一步精简模型结构，降低模型大小PSENet速度上还是比较慢，尝试更快的STD算法加入更多的训练数据加入对外部模型的支持加入数学公式检测（MFD）与 版面分析（Layout Analysis）模型加入对文档结构与表格的检测给作者来杯咖啡开源不易，如果此项目对您有帮助，可以考虑给作者来杯咖啡 ☕️。官方代码库：https://github.com/breezedeus/cnstd。