PaddleOCR 返回识别位置Word Box让 OCR 输出每个文字坐标的完整实践指南【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100 languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCR导读本文基于 PaddleOCR 仓库中「返回识别位置」的官方指南系统讲解如何让文档识别模型在返回识别内容之外同时返回每个文字中文单字 / 英文单词的位置框word box并配合版面恢复recovery流程将横排文档还原为带结构化坐标信息的 Word/Markdown 结果。读完本文你将掌握英文与中文两类文档的完整部署命令、四个推理模型检测、识别、表格、版面的下载与组织方式以及从命令行参数到后处理源码的完整调用链可直接用于需要对 OCR 结果做坐标级后处理的 AI 数据抽取、文档解析等场景。一、功能概述识别内容 每个字的位置根据横排文档的识别需求PaddleOCR 的识别模型不仅返回识别出的文本内容还可以返回每个文字的位置信息对于英文文档返回按空格切分的每个单词的包围框对于中文文档返回每个汉字字符的包围框。这一能力由--return_word_box参数开启其官方定义为“Whether return the bbox of each word (split by space) or chinese character. Only used in ppstructure for layout recovery”见 tools/infer/utility.py默认值为False。也就是说该功能主要在 PP-Structure 的版面恢复流程中使用用于在还原文档排版时精确标注每个词/字的位置。二、英文文档恢复实战2.1 下载推理模型首先进入ppstructure目录并准备推理模型目录cd PaddleOCR/ppstructure ## 创建并进入模型目录 mkdir inference cd inference ## 下载超轻量英文 PP-OCRv3 检测模型并解压 wget https://paddleocr.bj.bcebos.com/PP-OCRv3/english/en_PP-OCRv3_det_infer.tar tar xf en_PP-OCRv3_det_infer.tar ## 下载超轻量英文 PP-OCRv3 识别模型并解压 wget https://paddle-model-ecology.bj.bcebos.com/paddlex/official_inference_model/paddle3.0.0/en_PP-OCRv3_mobile_rec_infer.tar tar xf en_PP-OCRv3_mobile_rec_infer.tar ## 下载超轻量英文表格结构模型并解压 wget https://paddleocr.bj.bcebos.com/ppstructure/models/slanet/paddle3.0b2/en_ppstructure_mobile_v2.0_SLANet_infer.tar tar xf en_ppstructure_mobile_v2.0_SLANet_infer.tar ## 下载 publaynet 数据集的版面分析模型并解压 wget https://paddleocr.bj.bcebos.com/ppstructure/models/layout/picodet_lcnet_x1_0_fgd_layout_infer.tar tar xf picodet_lcnet_x1_0_fgd_layout_infer.tar cd ..四个模型分别承担文字检测det、文字识别rec、表格结构识别SLANet table、版面区域分析layout共同构成完整的 PP-Structure 结构化解析链路。2.2 执行推理命令在ppstructure/目录下运行注意各路径均相对于该目录python predict_system.py \ --image_dir../docs/ppstructure/images/table_1.png \ --det_model_dirinference/en_PP-OCRv3_det_infer \ --rec_model_dirinference/en_PP-OCRv3_mobile_rec_infer \ --rec_char_dict_path../ppocr/utils/en_dict.txt \ --table_model_dirinference/en_ppstructure_mobile_v2.0_SLANet_infer \ --table_char_dict_path../ppocr/utils/dict/table_structure_dict.txt \ --layout_model_dirinference/picodet_lcnet_x1_0_fgd_layout_infer \ --layout_dict_path../ppocr/utils/dict/layout_dict/layout_publaynet_dict.txt \ --vis_font_path../doc/fonts/simfang.ttf \ --recoveryTrue \ --output../output/ \ --return_word_boxTrue关键参数说明参数作用备注--image_dir输入图片路径可为单图或目录目录会自动遍历--det_model_dir/--rec_model_dir检测、识别模型目录英文场景使用en_PP-OCRv3_*系列--rec_char_dict_path识别字符字典英文用ppocr/utils/en_dict.txt--table_model_dir/--table_char_dict_path表格结构模型与其字典英文用table_structure_dict.txt--layout_model_dir/--layout_dict_path版面分析模型与其字典publaynet 数据集--vis_font_path可视化绘制字体英文用simfang.ttf中文用chinese_cht.ttf--recoveryTrue开启版面恢复关闭则只做版面结构分析--output结果输出根目录默认./output--return_word_boxTrue开启逐词/逐字位置框输出本指南核心开关默认False2.3 查看可视化结果推理完成后在../output/structure/table_1/show_0.jpg查看可视化结果。可视化图中每个英文单词都被绘制出独立的包围框与识别文本一一对应三、中文文档恢复实战3.1 下载推理模型中文场景同样需要四个模型但全部替换为中文/PP-OCRv3 版本cd PaddleOCR/ppstructure ## 进入模型目录 cd inference ## 下载超轻量中文 PP-OCRv3 检测模型并解压 wget https://paddle-model-ecology.bj.bcebos.com/paddlex/official_inference_model/paddle3.0.0/PP-OCRv3_mobile_det_infer.tar tar xf PP-OCRv3_mobile_det_infer.tar ## 下载超轻量中文 PP-OCRv3 识别模型并解压 wget https://paddle-model-ecology.bj.bcebos.com/paddlex/official_inference_model/paddle3.0.0/PP-OCRv3_mobile_rec_infer.tar tar xf PP-OCRv3_mobile_rec_infer.tar ## 下载超轻量中文表格结构模型并解压 wget https://paddleocr.bj.bcebos.com/ppstructure/models/slanet/paddle3.0b2/ch_ppstructure_mobile_v2.0_SLANet_infer.tar tar xf ch_ppstructure_mobile_v2.0_SLANet_infer.tar ## 下载 CDLA 数据集的版面分析模型并解压 wget https://paddleocr.bj.bcebos.com/ppstructure/models/layout/picodet_lcnet_x1_0_fgd_layout_cdla_infer.tar tar xf picodet_lcnet_x1_0_fgd_layout_cdla_infer.tar cd ..3.2 准备测试图片将如下测试图片命名为2.png放置到./docs/table/目录下该路径即后续--image_dir指向的输入3.3 执行推理命令在ppstructure/目录下运行python predict_system.py \ --image_dir./docs/table/2.png \ --det_model_dirinference/PP-OCRv3_mobile_det_infer \ --rec_model_dirinference/PP-OCRv3_mobile_rec_infer \ --rec_char_dict_path../ppocr/utils/ppocr_keys_v1.txt \ --table_model_dirinference/ch_ppstructure_mobile_v2.0_SLANet_infer \ --table_char_dict_path../ppocr/utils/dict/table_structure_dict_ch.txt \ --layout_model_dirinference/picodet_lcnet_x1_0_fgd_layout_cdla_infer \ --layout_dict_path../ppocr/utils/dict/layout_dict/layout_cdla_dict.txt \ --vis_font_path../doc/fonts/chinese_cht.ttf \ --recoveryTrue \ --output../output/ \ --return_word_boxTrue与英文命令的差异集中在字符字典改用ppocr/utils/ppocr_keys_v1.txt中文通用字典、表格字典改用table_structure_dict_ch.txt、版面字典改用 CDLA 中文文档数据集、字体改用chinese_cht.ttf。其余参数语义完全一致。3.4 查看可视化结果推理完成后在../output/structure/2/show_0.jpg查看可视化结果。可以看到每个汉字都被独立框出位置框粒度达到字符级四、源码级原理return_word_box的完整调用链理解该功能背后“从命令行到字符级坐标”的实现有助于你在二次开发时正确地消费这些位置数据。4.1 参数定义与传递--return_word_box定义于 tools/infer/utility.py随后在 ppstructure/predict_system.py 中被读入StructureSystem对象self.return_word_box args.return_word_box4.2 词级坐标计算入口在StructureSystem._predict_text()中见 ppstructure/predict_system.py当return_word_box为True时对每一行检测框box调用cal_ocr_word_box把识别字符串拆分为“逐词/逐字内容 逐词/逐字坐标”并连同行级结果一起组装成结构化字典if self.return_word_box: word_box_content_list, word_box_list cal_ocr_word_box( rec_str, box, rec_res[2] ) res.append({ text: rec_str, confidence: float(rec_conf), text_region: box.tolist(), text_word: word_box_content_list, text_word_region: word_box_list, })由此可见输出的 JSON 结果中新增了text_word每个词/字的文本列表与text_word_region每个词/字的四角点坐标列表可与text_region整行坐标配合用于坐标级后处理。4.3 字符分组与坐标反算cal_ocr_word_box实现在 ppstructure/utility.py其算法要点为识别结果中携带col_num特征序列列数与word_col_list每个词/字在特征序列中的列位置将行级检测框box按列数均分为cell_width的等宽单元由列位置反算出每个词的像素区间针对英文/数字ennum状态直接按列区间映射矩形框针对连续汉字cn状态先统计非汉字段的平均字宽avg_char_width再以每列中心点为中心、按平均字宽生成字符框从而在不等宽字体下也能得到较准确的单字框。这些“词/字状态”cn与ennum的切分逻辑由识别后处理中的CTCLabelDecode.get_word_info()完成见 ppocr/postprocess/rec_postprocess.py它将连续汉字、连续英文/数字含1.23、VGG-16、state-of-the-art等连写形式各自聚合成词而空格、括号等作为分隔符。4.4 识别后处理的透传在识别引擎侧return_word_box由 tools/infer/predict_rec.py 透传给CTCLabelDecode后处理算子rec_result self.postprocess_op( preds, return_word_boxself.return_word_box, wh_ratio_listwh_ratio_list, max_wh_ratiomax_wh_ratio, )CTCLabelDecode.__call__收到该参数后会在解码结果中追加word_list、word_col_list、state_list等信息见 ppocr/postprocess/rec_postprocess.py供上层cal_ocr_word_box使用。因此该功能依赖识别模型输出 CTC 特征序列的列级信息只有当识别后处理为CTCLabelDecode时才完整可用。4.5 结果可视化与落盘可视化draw_structure_result会遍历每个文本区域的text_word_region将逐词/逐字框绘制到结果图上空文本、置信度取 1.0见 ppstructure/utility.py这就是前文两张可视化图中“每个字/词一个框”的来源落盘save_structure_res将每个版面区域序列化为 JSON 写入res_{idx}.txt同时表格区域额外导出为.xlsx、图片区域导出为.jpg见 ppstructure/predict_system.py版面恢复当--recoveryTrue时main()还会调用sorted_layout_boxes与convert_info_docx/convert_info_markdown把带坐标的结构化结果还原为 Word / Markdown 文档见 ppstructure/predict_system.py。五、输出结果解读与常见问题5.1 结构化 JSON 字段开启--return_word_boxTrue后res_0.txt中每个版面区域的 JSON 核心字段如下{ type: text, bbox: [x1, y1, x2, y2], res: [ { text: PaddleOCR, confidence: 0.99, text_region: [[x1,y1],[x2,y1],[x2,y2],[x1,y2]], text_word: [Paddle, OCR], text_word_region: [[[x1,y1],[x2,y1],[x2,y2],[x1,y2]], ...] } ], img_idx: 0 }text_word与text_word_region一一对应可直接用于生成带高亮/锚点的文档、知识库坐标索引等下游任务。5.2 常见问题与前提模型与字典需配套英文链路使用en_dict.txt 英文模型中文链路使用ppocr_keys_v1.txt 中文模型混用会导致识别结果错乱字体文件路径--vis_font_path仅影响可视化绘制中文必须使用chinese_cht.ttf这类支持中文字符的字体否则中文无法正常渲染对应字体文件位于 doc/fonts 目录适用前提该功能面向横排文档的版面恢复场景正如文档开头所述“根据横排的文档”对竖排或倾斜严重的文档字级坐标的准确性会下降结果目录结构所有输出统一落在--output指定的目录下按structure/图片名/show_页序号.jpg与res_页序号.txt组织。六、总结--return_word_boxTrue是 PP-Structure 版面恢复流程中非常有价值的开关它把 OCR 的产出从“一行文本 一行坐标”细化为“逐词/逐字文本 逐词/逐字坐标”为文档转结构化数据、AI 知识抽取、坐标级版面还原提供了精细依据。本文给出的英文与中文两套命令可直接在 ppstructure/predict_system.py 所在目录运行其背后的实现链路StructureSystem._predict_text→cal_ocr_word_box→CTCLabelDecode.get_word_info也为二次开发提供了清晰的扩展入口。【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100 languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCR创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考