示例工程【免费下载链接】python-docs-samplesCode samples used on cloud.google.com项目地址https://gitcode.com/GitHub_Trending/py/python-docs-samples点击查看免费下载本文以 python-docs-samples 仓库中 vision/snippets/face_detection 目录下的官方示例为蓝本系统讲解如何使用 Google Cloud Vision API 在 Python 中完成人脸检测从环境认证、依赖安装、命令行运行到faces.py的源码级拆解、结果可视化绘制绿色人脸框与置信度再到测试用例的验证逻辑。读完本文你将能够独立跑通一个人脸检测 图像标注的完整流程并掌握如何基于 Vision API 的 FaceAnnotation 结果做进一步扩展。一、示例概览这个目录里有什么该示例位于仓库的 vision/snippets/face_detection/ 目录核心目标是在给定图片中检测人脸并用绿色方框把每张脸框出来、在方框上方标注检测置信度。目录内文件如下文件作用faces.py示例主程序检测人脸并绘制方框faces_test.py基于 pytest 的自动化测试验证方框确实被绘制requirements.txt运行时依赖google-cloud-vision与pillowrequirements-test.txt测试依赖pytestnoxfile_config.pynox 测试配置声明忽略的 Python 版本README.rst官方说明文档由 README.rst.in 自动生成从 README.rst.in 的元数据可以看到该示例归属于 Cloud Vision API 产品线被官方定义为 Face detection 示例。README.rst提到Cloud Vision API 允许开发者轻松地在应用中集成视觉检测能力包括图像标注image labeling、人脸与地标检测、光学字符识别OCR以及显性内容标记等本文聚焦其中的人脸检测face detection。注意仓库中还有更全面的 vision/snippets/detect/detect.py它提供了不带绘图功能的纯检测 打印人脸属性版本可作为本示例的对照与扩展素材后文会引用其中的实现细节。二、环境准备认证与依赖安装2.1 启用 API 与设置认证调用 Cloud Vision API 前必须完成认证设置在 Google Cloud 控制台创建或选择一个项目并启用Cloud Vision API为本机环境配置应用默认凭据Application Default Credentials常见做法是下载服务账号 JSON 密钥并通过环境变量GOOGLE_APPLICATION_CREDENTIALS指向该文件建议同步安装并登录 Google Cloud SDK便于后续在本地通过gcloud管理凭据。完成认证后faces.py 中的vision.ImageAnnotatorClient()才能无参数直接构造客户端——它会自动从环境凭据中读取身份信息。2.2 克隆仓库并创建虚拟环境从仓库检出代码后进入示例目录。示例源码兼容 Python 2.7 与 3.4结合 requirements.txt 中的版本约束pillow12.3.0; python_version 3.10实际推荐在 Python 3.10 环境下运行。# 进入仓库后切换到示例目录 cd vision/snippets/face_detection # 创建并激活虚拟环境如尚未安装 virtualenv先 pip install virtualenv virtualenv env source env/bin/activate # 安装运行依赖 pip install -r requirements.txt安装的依赖版本见 requirements.txtgoogle-cloud-vision3.8.1Vision API 官方 Python 客户端pillow12.3.0Python 3.10用于打开图片、绘制方框与保存输出。三、运行示例命令行参数详解激活虚拟环境后直接运行python faces.py程序会打印完整的命令行帮助与仓库中 README.rst 记录的一致usage: faces.py [-h] [--out OUTPUT] [--max-results MAX_RESULTS] input_image Detects faces in the given image. positional arguments: input_image the image youd like to detect faces in. optional arguments: -h, --help show this help message and exit --out OUTPUT the name of the output file. --max-results MAX_RESULTS the max results of face detection.各参数在 faces.py 的argparse定义中一一对应参数含义默认值类型input_image位置参数待检测人脸的本地图片路径必填无str--out输出图片文件名绘制方框后保存out.jpgstr--max-results最多返回的人脸检测结果数量4int一个完整的调用示例python faces.py ./my_photo.jpg --out ./annotated.jpg --max-results 10程序运行后会输出两行信息检测到的人脸数量如Found 3 faces与输出文件名Writing to file out.jpg随后在当前目录生成带绿色方框的标注图片。四、源码拆解faces.py 的三层实现faces.py 将整个流程拆成三个职责清晰的函数彼此通过main串联。4.1 发送检测请求detect_face()detect_face() 负责调用 Vision APIdef detect_face(face_file, max_results4): client vision.ImageAnnotatorClient() content face_file.read() image vision.Image(contentcontent) return client.face_detection(imageimage, max_resultsmax_results).face_annotations关键点vision.ImageAnnotatorClient()是 Vision API 的统一入口客户端通过face_detection()方法发起人脸检测请求图片以二进制内容通过vision.Image(contentcontent)传入face_file是一个文件类对象file-like object因此调用方需要以二进制模式打开文件max_results控制最多返回的人脸数与命令行参数--max-results直接对应返回的face_annotations是FaceAnnotation对象列表每个对象包含bounding_poly人脸边界多边形与detection_confidence检测置信度等字段。4.2 绘制结果highlight_faces()highlight_faces() 使用 Pillow 完成可视化def highlight_faces(image, faces, output_filename): im Image.open(image) draw ImageDraw.Draw(im) for face in faces: box [(vertex.x, vertex.y) for vertex in face.bounding_poly.vertices] draw.line(box [box[0]], width5, fill#00ff00) draw.text( ( (face.bounding_poly.vertices)[0].x, (face.bounding_poly.vertices)[0].y - 30, ), str(format(face.detection_confidence, .3f)) %, fill#FF0000, ) im.save(output_filename)实现细节值得展开方框绘制把face.bounding_poly.vertices四个角点转换为(x, y)坐标列表draw.line(box [box[0]], ...)通过把首点追加到末尾形成闭合的四边形边框线条宽度为 5 像素颜色为绿色#00ff00置信度标注取左上角顶点vertices[0]在其上方 30 像素处用红色#FF0000文本绘制检测置信度格式为保留三位小数的百分比字符串如0.972%输出保存im.save(output_filename)把标注后的图片写回磁盘默认文件名即out.jpg。4.3 主流程串联main()main() 负责文件管理与流程编排def main(input_filename, output_filename, max_results): with open(input_filename, rb) as image: faces detect_face(image, max_results) print(Found {} face{}.format(len(faces), if len(faces) 1 else s)) print(fWriting to file {output_filename}) image.seek(0) highlight_faces(image, faces, output_filename)注意其中两个容易被忽略的细节文件指针重置detect_face读取文件后文件指针已到末尾因此在把同一文件对象传给highlight_faces前必须调用image.seek(0)回到文件开头否则 Pillow 会读到空内容单复数文案Found {} face{}.format(len(faces), if len(faces) 1 else s)根据检测数量自动输出face或faces保证输出语句通顺。入口部分faces.py则通过argparse完成参数解析--out的destoutput将参数映射到main的output_filename--max-results的typeint保证解析为整数并传给main(args.input_image, args.output, args.max_results)。五、从源码结构看FaceAnnotation 的更多可用信息本示例只使用了bounding_poly与detection_confidence两个字段但仓库内 vision/snippets/detect/detect.py 的detect_faces()展示了 FaceAnnotation 对象的更多属性可直接作为扩展参考情感倾向概率face.anger_likelihood、face.joy_likelihood、face.surprise_likelihood等字段取值来自google.cloud.vision.enums的似然度枚举UNKNOWN、VERY_UNLIKELY、UNLIKELY、POSSIBLE、LIKELY、VERY_LIKELY边界坐标face.bounding_poly.vertices每个顶点的(x, y)与 faces.py 中绘制方框用的是同一字段错误处理范式detect.py 在遍历结果后检查response.error.message若非空则抛出带错误提示的Exception——这是调用 Vision API 时推荐保留的防御性写法GCS/URL 图片detect_faces_uri() 展示了另一种输入方式不传二进制内容而是通过image.source.image_uri uri指定 Google Cloud Storage 对象或公开网页图片地址适合大图或远程资源的场景。从源码结构看faces.py的detect_face与detect.py的detect_faces调用的是同一个底层方法client.face_detection(...)区别仅在于对响应结果的使用方式——前者侧重空间可视化后者侧重属性打印。开发者可以按需组合这两套字段实现画框 打印情绪标签的增强版本。六、测试验证faces_test.py 如何证明功能正确faces_test.py 用 pytest 编写了一个端到端冒烟测试逻辑设计非常直观def test_main(tmpdir): out_file os.path.join(tmpdir.dirname, face-output.jpg) in_file os.path.join(RESOURCES, face-input.jpg) # 输入图片中不应存在绿色像素纯 (0, 255, 0) im Image.open(in_file) greens sum(1 for (r, g, b) in im.getdata() if r 0 and g 255 and b 0) assert greens 1 main(in_file, out_file, 10) # 输出图片中应出现足够多的绿色像素方框已绘制 im Image.open(out_file) greens sum(1 for (r, g, b) in im.getdata() if r 0 and g 255 and b 0) assert greens 10测试要点前置校验先遍历输入图片像素断言绿色像素数小于 1确保输入图本身不含#00ff00绿色从而避免误判执行主流程调用main(in_file, out_file, 10)即用--max-results 10的语义处理resources下的face-input.jpg后置断言再统计输出图片的绿色像素数断言大于 10——只要highlight_faces成功画出了绿色方框width5 的闭合四边形该条件必然满足。该测试同时验证了检测链路Vision API 请求成功、返回了人脸与绘图链路Pillow 正确保存标注图。运行测试只需安装测试依赖后执行pytest依赖版本见 requirements-test.txt。需要注意的是此类测试会真实调用 Cloud Vision API因此需要有效的认证凭据noxfile_config.py 中通过ignored_versions排除了 Python 3.8、3.9、3.11、3.12、3.13仅保留特定版本用于 CI 测试矩阵。七、常见问题与使用限制结合源码与仓库配置运行本示例时需留意以下几点认证缺失导致调用失败vision.ImageAnnotatorClient()在无可用凭据时会抛出异常务必先完成 2.1 节的认证设置输入图片格式detect_face直接读取文件二进制内容Vision API 支持 JPEG、PNG、GIF、BMP、WEBP、RAW、ICO、PDF、TIFF 等常见格式输出目录权限highlight_faces会把结果写入当前工作目录默认文件名out.jpg确保运行目录可写max_results 语义该参数限制单次请求最多返回的人脸数若图片中人脸超过该值超出部分不会被处理也不会出现在方框标注中网络依赖每次运行都需要访问 Cloud Vision API 服务离线环境无法使用图片过大的场景可考虑先上传到 GCS再改用detect_faces_uri式的 URI 输入参考 detect.py。八、小结从 README.rst 的一句话示例说明出发结合 faces.py 的实现与 faces_test.py 的验证本示例完整覆盖了鉴权 → 构造客户端 → 发送人脸检测请求 → 解析 FaceAnnotation → 用 Pillow 可视化 → 测试回归的整条链路。它既是 Cloud Vision API 人脸检测功能的最小可运行范例也是学习 Vision API 客户端编程范式ImageAnnotatorClient 响应注解对象的入门教材。在此基础上读者完全可以参照 detect.py 中的情感似然度字段与错误处理模板将示例扩展为带情绪分析、多图批量处理甚至人脸裁剪入库的实战工具。赞分享示例工程【免费下载链接】python-docs-samplesCode samples used on cloud.google.com项目地址https://gitcode.com/GitHub_Trending/py/python-docs-samples点击查看免费下载相关推荐如何从零搭好 Source SDK 2013一份能直接上手的完整 Mod 开发指南如何从零搭好 Source SDK 2013一份能直接上手的完整 Mod 开发指南 Source SDK 2013 是 Valve 开源的 Source 游戏示例工程python-docs-samples 实战基于 Google Cloud Endpoints 的 Python Echo API 从本地调试到生产部署全指南python docs samples 实战基于 Google Cloud Endpoints 的 Python Echo API 从本地调试到生产部署全指南示例工程Google Cloud Monitoring Alerting API 实战指南基于 python-docs-samples 的告警策略全生命周期管理Google Cloud Monitoring Alerting API 实战指南基于 python docs samples 的告警策略全生命周期管理 本篇示例工程上一篇SerenityOS 在 Windows 上构建与运行完整指南WSL2 QEMU WHPX 硬件加速下一篇Reflex 浏览器存储 API 实战指南Cookie、LocalStorage 与 SessionStorage 的完整用法创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Google Cloud Vision API 人脸检测实战：基于 python-docs-samples 的 faces.py 全面指南
示例工程【免费下载链接】python-docs-samplesCode samples used on cloud.google.com项目地址https://gitcode.com/GitHub_Trending/py/python-docs-samples点击查看免费下载本文以 python-docs-samples 仓库中 vision/snippets/face_detection 目录下的官方示例为蓝本系统讲解如何使用 Google Cloud Vision API 在 Python 中完成人脸检测从环境认证、依赖安装、命令行运行到faces.py的源码级拆解、结果可视化绘制绿色人脸框与置信度再到测试用例的验证逻辑。读完本文你将能够独立跑通一个人脸检测 图像标注的完整流程并掌握如何基于 Vision API 的 FaceAnnotation 结果做进一步扩展。一、示例概览这个目录里有什么该示例位于仓库的 vision/snippets/face_detection/ 目录核心目标是在给定图片中检测人脸并用绿色方框把每张脸框出来、在方框上方标注检测置信度。目录内文件如下文件作用faces.py示例主程序检测人脸并绘制方框faces_test.py基于 pytest 的自动化测试验证方框确实被绘制requirements.txt运行时依赖google-cloud-vision与pillowrequirements-test.txt测试依赖pytestnoxfile_config.pynox 测试配置声明忽略的 Python 版本README.rst官方说明文档由 README.rst.in 自动生成从 README.rst.in 的元数据可以看到该示例归属于 Cloud Vision API 产品线被官方定义为 Face detection 示例。README.rst提到Cloud Vision API 允许开发者轻松地在应用中集成视觉检测能力包括图像标注image labeling、人脸与地标检测、光学字符识别OCR以及显性内容标记等本文聚焦其中的人脸检测face detection。注意仓库中还有更全面的 vision/snippets/detect/detect.py它提供了不带绘图功能的纯检测 打印人脸属性版本可作为本示例的对照与扩展素材后文会引用其中的实现细节。二、环境准备认证与依赖安装2.1 启用 API 与设置认证调用 Cloud Vision API 前必须完成认证设置在 Google Cloud 控制台创建或选择一个项目并启用Cloud Vision API为本机环境配置应用默认凭据Application Default Credentials常见做法是下载服务账号 JSON 密钥并通过环境变量GOOGLE_APPLICATION_CREDENTIALS指向该文件建议同步安装并登录 Google Cloud SDK便于后续在本地通过gcloud管理凭据。完成认证后faces.py 中的vision.ImageAnnotatorClient()才能无参数直接构造客户端——它会自动从环境凭据中读取身份信息。2.2 克隆仓库并创建虚拟环境从仓库检出代码后进入示例目录。示例源码兼容 Python 2.7 与 3.4结合 requirements.txt 中的版本约束pillow12.3.0; python_version 3.10实际推荐在 Python 3.10 环境下运行。# 进入仓库后切换到示例目录 cd vision/snippets/face_detection # 创建并激活虚拟环境如尚未安装 virtualenv先 pip install virtualenv virtualenv env source env/bin/activate # 安装运行依赖 pip install -r requirements.txt安装的依赖版本见 requirements.txtgoogle-cloud-vision3.8.1Vision API 官方 Python 客户端pillow12.3.0Python 3.10用于打开图片、绘制方框与保存输出。三、运行示例命令行参数详解激活虚拟环境后直接运行python faces.py程序会打印完整的命令行帮助与仓库中 README.rst 记录的一致usage: faces.py [-h] [--out OUTPUT] [--max-results MAX_RESULTS] input_image Detects faces in the given image. positional arguments: input_image the image youd like to detect faces in. optional arguments: -h, --help show this help message and exit --out OUTPUT the name of the output file. --max-results MAX_RESULTS the max results of face detection.各参数在 faces.py 的argparse定义中一一对应参数含义默认值类型input_image位置参数待检测人脸的本地图片路径必填无str--out输出图片文件名绘制方框后保存out.jpgstr--max-results最多返回的人脸检测结果数量4int一个完整的调用示例python faces.py ./my_photo.jpg --out ./annotated.jpg --max-results 10程序运行后会输出两行信息检测到的人脸数量如Found 3 faces与输出文件名Writing to file out.jpg随后在当前目录生成带绿色方框的标注图片。四、源码拆解faces.py 的三层实现faces.py 将整个流程拆成三个职责清晰的函数彼此通过main串联。4.1 发送检测请求detect_face()detect_face() 负责调用 Vision APIdef detect_face(face_file, max_results4): client vision.ImageAnnotatorClient() content face_file.read() image vision.Image(contentcontent) return client.face_detection(imageimage, max_resultsmax_results).face_annotations关键点vision.ImageAnnotatorClient()是 Vision API 的统一入口客户端通过face_detection()方法发起人脸检测请求图片以二进制内容通过vision.Image(contentcontent)传入face_file是一个文件类对象file-like object因此调用方需要以二进制模式打开文件max_results控制最多返回的人脸数与命令行参数--max-results直接对应返回的face_annotations是FaceAnnotation对象列表每个对象包含bounding_poly人脸边界多边形与detection_confidence检测置信度等字段。4.2 绘制结果highlight_faces()highlight_faces() 使用 Pillow 完成可视化def highlight_faces(image, faces, output_filename): im Image.open(image) draw ImageDraw.Draw(im) for face in faces: box [(vertex.x, vertex.y) for vertex in face.bounding_poly.vertices] draw.line(box [box[0]], width5, fill#00ff00) draw.text( ( (face.bounding_poly.vertices)[0].x, (face.bounding_poly.vertices)[0].y - 30, ), str(format(face.detection_confidence, .3f)) %, fill#FF0000, ) im.save(output_filename)实现细节值得展开方框绘制把face.bounding_poly.vertices四个角点转换为(x, y)坐标列表draw.line(box [box[0]], ...)通过把首点追加到末尾形成闭合的四边形边框线条宽度为 5 像素颜色为绿色#00ff00置信度标注取左上角顶点vertices[0]在其上方 30 像素处用红色#FF0000文本绘制检测置信度格式为保留三位小数的百分比字符串如0.972%输出保存im.save(output_filename)把标注后的图片写回磁盘默认文件名即out.jpg。4.3 主流程串联main()main() 负责文件管理与流程编排def main(input_filename, output_filename, max_results): with open(input_filename, rb) as image: faces detect_face(image, max_results) print(Found {} face{}.format(len(faces), if len(faces) 1 else s)) print(fWriting to file {output_filename}) image.seek(0) highlight_faces(image, faces, output_filename)注意其中两个容易被忽略的细节文件指针重置detect_face读取文件后文件指针已到末尾因此在把同一文件对象传给highlight_faces前必须调用image.seek(0)回到文件开头否则 Pillow 会读到空内容单复数文案Found {} face{}.format(len(faces), if len(faces) 1 else s)根据检测数量自动输出face或faces保证输出语句通顺。入口部分faces.py则通过argparse完成参数解析--out的destoutput将参数映射到main的output_filename--max-results的typeint保证解析为整数并传给main(args.input_image, args.output, args.max_results)。五、从源码结构看FaceAnnotation 的更多可用信息本示例只使用了bounding_poly与detection_confidence两个字段但仓库内 vision/snippets/detect/detect.py 的detect_faces()展示了 FaceAnnotation 对象的更多属性可直接作为扩展参考情感倾向概率face.anger_likelihood、face.joy_likelihood、face.surprise_likelihood等字段取值来自google.cloud.vision.enums的似然度枚举UNKNOWN、VERY_UNLIKELY、UNLIKELY、POSSIBLE、LIKELY、VERY_LIKELY边界坐标face.bounding_poly.vertices每个顶点的(x, y)与 faces.py 中绘制方框用的是同一字段错误处理范式detect.py 在遍历结果后检查response.error.message若非空则抛出带错误提示的Exception——这是调用 Vision API 时推荐保留的防御性写法GCS/URL 图片detect_faces_uri() 展示了另一种输入方式不传二进制内容而是通过image.source.image_uri uri指定 Google Cloud Storage 对象或公开网页图片地址适合大图或远程资源的场景。从源码结构看faces.py的detect_face与detect.py的detect_faces调用的是同一个底层方法client.face_detection(...)区别仅在于对响应结果的使用方式——前者侧重空间可视化后者侧重属性打印。开发者可以按需组合这两套字段实现画框 打印情绪标签的增强版本。六、测试验证faces_test.py 如何证明功能正确faces_test.py 用 pytest 编写了一个端到端冒烟测试逻辑设计非常直观def test_main(tmpdir): out_file os.path.join(tmpdir.dirname, face-output.jpg) in_file os.path.join(RESOURCES, face-input.jpg) # 输入图片中不应存在绿色像素纯 (0, 255, 0) im Image.open(in_file) greens sum(1 for (r, g, b) in im.getdata() if r 0 and g 255 and b 0) assert greens 1 main(in_file, out_file, 10) # 输出图片中应出现足够多的绿色像素方框已绘制 im Image.open(out_file) greens sum(1 for (r, g, b) in im.getdata() if r 0 and g 255 and b 0) assert greens 10测试要点前置校验先遍历输入图片像素断言绿色像素数小于 1确保输入图本身不含#00ff00绿色从而避免误判执行主流程调用main(in_file, out_file, 10)即用--max-results 10的语义处理resources下的face-input.jpg后置断言再统计输出图片的绿色像素数断言大于 10——只要highlight_faces成功画出了绿色方框width5 的闭合四边形该条件必然满足。该测试同时验证了检测链路Vision API 请求成功、返回了人脸与绘图链路Pillow 正确保存标注图。运行测试只需安装测试依赖后执行pytest依赖版本见 requirements-test.txt。需要注意的是此类测试会真实调用 Cloud Vision API因此需要有效的认证凭据noxfile_config.py 中通过ignored_versions排除了 Python 3.8、3.9、3.11、3.12、3.13仅保留特定版本用于 CI 测试矩阵。七、常见问题与使用限制结合源码与仓库配置运行本示例时需留意以下几点认证缺失导致调用失败vision.ImageAnnotatorClient()在无可用凭据时会抛出异常务必先完成 2.1 节的认证设置输入图片格式detect_face直接读取文件二进制内容Vision API 支持 JPEG、PNG、GIF、BMP、WEBP、RAW、ICO、PDF、TIFF 等常见格式输出目录权限highlight_faces会把结果写入当前工作目录默认文件名out.jpg确保运行目录可写max_results 语义该参数限制单次请求最多返回的人脸数若图片中人脸超过该值超出部分不会被处理也不会出现在方框标注中网络依赖每次运行都需要访问 Cloud Vision API 服务离线环境无法使用图片过大的场景可考虑先上传到 GCS再改用detect_faces_uri式的 URI 输入参考 detect.py。八、小结从 README.rst 的一句话示例说明出发结合 faces.py 的实现与 faces_test.py 的验证本示例完整覆盖了鉴权 → 构造客户端 → 发送人脸检测请求 → 解析 FaceAnnotation → 用 Pillow 可视化 → 测试回归的整条链路。它既是 Cloud Vision API 人脸检测功能的最小可运行范例也是学习 Vision API 客户端编程范式ImageAnnotatorClient 响应注解对象的入门教材。在此基础上读者完全可以参照 detect.py 中的情感似然度字段与错误处理模板将示例扩展为带情绪分析、多图批量处理甚至人脸裁剪入库的实战工具。赞分享示例工程【免费下载链接】python-docs-samplesCode samples used on cloud.google.com项目地址https://gitcode.com/GitHub_Trending/py/python-docs-samples点击查看免费下载相关推荐如何从零搭好 Source SDK 2013一份能直接上手的完整 Mod 开发指南如何从零搭好 Source SDK 2013一份能直接上手的完整 Mod 开发指南 Source SDK 2013 是 Valve 开源的 Source 游戏示例工程python-docs-samples 实战基于 Google Cloud Endpoints 的 Python Echo API 从本地调试到生产部署全指南python docs samples 实战基于 Google Cloud Endpoints 的 Python Echo API 从本地调试到生产部署全指南示例工程Google Cloud Monitoring Alerting API 实战指南基于 python-docs-samples 的告警策略全生命周期管理Google Cloud Monitoring Alerting API 实战指南基于 python docs samples 的告警策略全生命周期管理 本篇示例工程上一篇SerenityOS 在 Windows 上构建与运行完整指南WSL2 QEMU WHPX 硬件加速下一篇Reflex 浏览器存储 API 实战指南Cookie、LocalStorage 与 SessionStorage 的完整用法创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考