示例工程【免费下载链接】python-docs-samplesCode samples used on cloud.google.com项目地址https://gitcode.com/GitHub_Trending/py/python-docs-samples点击查看免费下载导读本文基于 python-docs-samples 仓库中的 vision/snippets/document_text 示例系统讲解如何使用 Google Cloud Vision API 的**文档文字检测Document Text Detection能力对图片中的文档进行 OCR 识别并将检测到的文本块Block、段落Paragraph、单词Word**的边界框绘制在原图上。读完本文你将掌握doctext.py的完整调用链、Vision API 的full_text_annotation数据结构Page → Block → Paragraph → Word → Symbol 五级层级、命令行参数用法以及如何在本仓库中运行与测试该示例。一、示例概览Vision API 与文档文字检测Google Cloud Vision API 允许开发者轻松将视觉检测功能集成到应用中包括图像标签、人脸与地标检测、光学字符识别OCR以及显性内容标记。本目录中的document_text示例聚焦于其中的 OCR 场景——尤其是对整页文档进行结构化文本识别而非简单的单行文字识别。与vision/snippets/detect中面向普通文本的detect_text不同doctext.py调用的是专门针对文档场景的document_text_detection方法返回结果中带有完整的版面层级结构可以精确到每个符号Symbol的坐标因此特别适合菜单、合同、票据、书籍扫描件等版面化文档的解析与可视化。本示例的核心文件文件作用doctext.py主程序OCR 识别 边界框绘制doctext_test.py测试验证输出图片成功生成requirements.txt运行时依赖google-cloud-vision、pillowrequirements-test.txt测试依赖pytestnoxfile_config.pynox 测试矩阵配置README.rst.in用于自动生成 README.rst 的元数据源注意本目录中的 README.rst 由工具自动生成文件首行注明 This file is automatically generated其结构化内容来自 README.rst.in。二、环境准备与依赖安装2.1 认证Authentication调用 Vision API 前必须完成认证配置。示例默认通过**应用默认凭据ADC**机制读取凭据推荐方式是在本地执行gcloud auth application-default login或为运行环境设置GOOGLE_APPLICATION_CREDENTIALS环境变量指向服务账号 JSON 密钥文件。所有云端 API 调用包括本例中的ImageAnnotatorClient都依赖该凭据完成鉴权。2.2 安装依赖示例使用 Python 编写依赖清单如下见 requirements.txtgoogle-cloud-vision3.8.1 pillow12.3.0; python_version 3.10安装步骤在仓库根目录下执行$ git clone https://gitcode.com/GitHub_Trending/py/python-docs-samples $ cd vision/snippets/document_text $ virtualenv env $ source env/bin/activate $ pip install -r requirements.txtgoogle-cloud-vision是 Vision API 的官方 Python 客户端库提供ImageAnnotatorClient等高层 APIpillowPIL用于打开图片并绘制边界框从 requirements.txt 可以看到pillow12.3.0带python_version 3.10的环境标记说明当前示例面向 Python 3.10。2.3 测试矩阵说明noxfile_config.py 中通过TEST_CONFIG_OVERRIDE配置了 nox 自动化测试的 Python 版本矩阵TEST_CONFIG_OVERRIDE { ignored_versions: [3.8, 3.9, 3.11, 3.12, 3.13], }即默认只在 Python 3.10 上运行测试其余版本被忽略。这与依赖清单中 Pillow 的环境标记相互印证——当前示例的可用运行环境以 Python 3.10 为准。三、运行示例与命令行参数在安装好依赖并完成认证后直接运行$ python doctext.py detect_file [-out_file OUTPUT_FILE]以仓库中常见示例图片为例$ python doctext.py resources/text_menu.jpg程序的完整帮助信息如下usage: doctext.py [-h] [-out_file OUT_FILE] detect_file positional arguments: detect_file The image for text detection. optional arguments: -h, --help show this help message and exit -out_file OUT_FILE Optional output file参数解析逻辑位于 doctext.py 的__main__入口参数类型必填说明detect_file位置参数是待检测文字的图片路径-out_file可选参数否输出图片路径默认值为0当-out_file未指定时代码会调用image.show()直接弹出图片预览窗口指定了输出路径则将绘制结果保存为文件if fileout ! 0: image.save(fileout) else: image.show()四、源码深度解析从图片到边界框doctext.py的完整处理流程可拆解为三个阶段特征枚举 → 调用 API 获取结构化文本 → 绘制边界框。4.1 特征类型枚举class FeatureType(Enum): PAGE 1 BLOCK 2 PARA 3 WORD 4 SYMBOL 5该枚举对应 Vision API 文档识别结果的五级版面层级页面PAGE→ 文本块BLOCK→ 段落PARA→ 单词WORD→ 符号SYMBOL。示例实际绘制时使用了其中三级BLOCK、PARA、WORD但枚举中保留了完整的层级以便按需扩展。4.2 调用文档文字检测 API核心函数get_document_bounds见 doctext.py完成了 API 调用与特征收集client vision.ImageAnnotatorClient() with open(image_file, rb) as image_file: content image_file.read() image vision.Image(contentcontent) response client.document_text_detection(imageimage) document response.full_text_annotation关键点读取图片字节以二进制模式打开图片并读取全部内容构造vision.Image(contentcontent)对象调用方法client.document_text_detection(imageimage)是文档文字检测的专用方法与通用文本检测text_detection相比返回的full_text_annotation包含完整的页面布局结构响应结构response.full_text_annotation是核心对象其内部嵌套了pages → blocks → paragraphs → words → symbols五级结构每一级都带有bounding_box顶点坐标和confidence置信度。4.3 遍历文档结构收集边界框for page in document.pages: for block in page.blocks: for paragraph in block.paragraphs: for word in paragraph.words: for symbol in word.symbols: if feature FeatureType.SYMBOL: bounds.append(symbol.bounding_box) if feature FeatureType.WORD: bounds.append(word.bounding_box) if feature FeatureType.PARA: bounds.append(paragraph.bounding_box) if feature FeatureType.BLOCK: bounds.append(block.bounding_box)这是一个自底向上的过滤收集过程无论请求哪个层级都完整遍历全部符号然后在对应的层级把bounding_box追加到bounds列表。因此函数能够按需返回某一层级所有元素的坐标集合为后续按层级着色绘制做好准备。4.4 边界框绘制draw_boxes函数见 doctext.py使用 PIL 的ImageDraw.Draw在图片上绘制多边形边框draw ImageDraw.Draw(image) for bound in bounds: draw.polygon( [ bound.vertices[0].x, bound.vertices[0].y, bound.vertices[1].x, bound.vertices[1].y, bound.vertices[2].x, bound.vertices[2].y, bound.vertices[3].x, bound.vertices[3].y, ], None, color, )每个bounding_box是一个四边形vertices[0..3]通常为左上、右上、右下、左下draw.polygon的第三个参数color指定边框颜色None表示不填充内部。4.5 三级着色渲染render_doc_text函数见 doctext.py将上述能力组合为完整的可视化流程image Image.open(filein) bounds get_document_bounds(filein, FeatureType.BLOCK) draw_boxes(image, bounds, blue) bounds get_document_bounds(filein, FeatureType.PARA) draw_boxes(image, bounds, red) bounds get_document_bounds(filein, FeatureType.WORD) draw_boxes(image, bounds, yellow)注意这里对同一张图片调用了三次get_document_bounds每次请求不同的特征层级并用不同颜色叠加绘制蓝色边框文本块BLOCK——对应版面中的整块区域如菜单中的整列红色边框段落PARA——块内的语义段落黄色边框单词WORD——细粒度的词级边界。这种蓝块、红段、黄词的三层可视化让文档版式结构一目了然是理解 OCR 版面分析结果的直观手段。若需要更细粒度如单个字符只需在枚举中加入FeatureType.SYMBOL的分支判断即可。五、测试验证仓库提供了针对该示例的自动化测试 doctext_test.pydef test_text() - None: Checks the output image for drawing the crop hint is created. doctext.render_doc_text(resources/text_menu.jpg, output-text.jpg) assert os.path.isfile(output-text.jpg)测试逻辑说明直接调用doctext.render_doc_text()而非通过命令行入口验证核心渲染函数可独立工作输入图片为resources/text_menu.jpg菜单类文档图与 README 中的示例用法一致输出到output-text.jpg后断言文件确实生成从而验证OCR 调用 边界框绘制 图片保存整条链路无异常。结合 noxfile_config.py 的版本配置可在 Python 3.10 环境下运行$ pytest doctext_test.py六、进一步扩展方向基于本示例的架构可以自然地扩展出以下实战能力细粒度字符识别在get_document_bounds中增加对FeatureType.SYMBOL的收集实现逐字符边界框输出可用于手写识别或印章检测提取纯文本full_text_annotation.text字段直接保存了识别出的全部文本内容可将其与坐标信息组合输出为结构化数据如 JSON/CSV用于文档归档、票据录入置信度过滤word.confidence等字段可用于筛选低置信度区域辅助人工复核批量处理将render_doc_text放入循环即可对整批扫描文档执行识别 可视化标注流水线。七、小结vision/snippets/document_text是一个短小精悍但完整的 Vision API 文档 OCR 示例它展示了认证 → 安装依赖 → 调用document_text_detection→ 解析full_text_annotation五级层级结构 → 按 Block/Para/Word 三级着色绘制边界框的完整链路并配套了可自动运行的 pytest 测试。无论你是要快速验证 Vision API 的 OCR 能力还是需要以此为起点构建生产级的文档解析管线都可以直接在本仓库中运行、修改并复用这份代码。相关文件索引示例主程序doctext.py自动化测试doctext_test.py运行时依赖requirements.txt测试配置noxfile_config.pyREADME 生成源README.rst.in同目录其他 Vision 示例vision/snippets含 detect、face_detection、crop_hints、web、product_search 等赞分享示例工程【免费下载链接】python-docs-samplesCode samples used on cloud.google.com项目地址https://gitcode.com/GitHub_Trending/py/python-docs-samples点击查看免费下载相关推荐5分钟上手Google Cloud Vision API实战指南5分钟上手Google Cloud Vision API实战指南 快速集成AI视觉能力让你的应用秒变火眼金睛Google Cloud Vision如何从零搭好 Source SDK 2013一份能直接上手的完整 Mod 开发指南如何从零搭好 Source SDK 2013一份能直接上手的完整 Mod 开发指南 Source SDK 2013 是 Valve 开源的 Source 游戏示例工程CameraKit-Android文本识别终极指南如何快速集成Google Vision API实现实时文字检测CameraKit Android文本识别终极指南如何快速集成Google Vision API实现实时文字检测 CameraKit Android是一个强大移动开发音视频上一篇如何在Windows上创建完美虚拟显示器ParsecVDisplay完整指南下一篇PyQt5 高级控件实战QPixmap、QLineEdit、QSplitter 与 QComboBox 完全指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考