Python 3.7+ 环境下，用 onvif_zeep 库快速控制海康/大华摄像头（保姆级避坑指南）-开发者社区

Python 3.7+环境下onvif_zeep库实战：海康/大华摄像头控制全解析

1. 环境准备与库选择

在开始之前，我们需要明确几个关键点。首先，ONVIF协议本身并不直接提供视频流传输功能，它主要用于设备发现、配置和控制。其次，Python生态中有多个ONVIF客户端库，但不同Python版本对应的库差异很大，选错会导致无法正常使用。

对于Python 3.7+环境，我们推荐使用onvif_zeep库，它是目前维护最活跃、兼容性最好的选择。安装非常简单：

pip install onvif_zeep

但实际安装过程中，可能会遇到一些依赖问题。以下是常见问题及解决方案：

问题1：zeep版本冲突
- 解决方案：指定zeep版本安装
```
pip install zeep==4.1.0
```
问题2：缺少httpx依赖
- 解决方案：额外安装异步HTTP客户端
```
pip install httpx
```
问题3：Windows平台SSL错误
- 解决方案：安装Python证书包
```
pip install python-certifi-win32
```

2. 设备连接与基础配置

成功安装库后，第一步是建立与摄像头的连接。海康和大华摄像头虽然都支持ONVIF协议，但在具体实现上有些微差异，需要特别注意。

2.1 初始化摄像头连接

from onvif import ONVIFCamera # 替换为你的摄像头实际IP和凭据 mycam = ONVIFCamera( '192.168.1.64', # 摄像头IP 80, # ONVIF服务端口，通常为80 'admin', # 用户名 'password' # 密码 ) # 创建媒体服务 media_service = mycam.create_media_service() # 获取第一个配置文档 media_profile = media_service.GetProfiles()[0]

注意：海康摄像头默认ONVIF端口可能是8000而非80，如果连接失败可以尝试修改端口号

2.2 验证设备信息

连接成功后，我们可以获取设备基本信息来验证连接是否正常：

# 获取设备信息 device_info = mycam.devicemgmt.GetDeviceInformation() print(f"制造商: {device_info.Manufacturer}") print(f"型号: {device_info.Model}") print(f"固件版本: {device_info.FirmwareVersion}") # 获取网络配置 network_config = mycam.devicemgmt.GetNetworkInterfaces() for interface in network_config: print(f"接口: {interface.Info.Name}, IP: {interface.IPv4.Config.Manual[0].Address}")

3. PTZ控制实战

PTZ(云台控制)是摄像头控制中最常用的功能之一，包括平移(Pan)、倾斜(Tilt)和变焦(Zoom)。下面我们详细讲解如何实现这些功能。

3.1 创建PTZ服务

# 创建PTZ服务 ptz_service = mycam.create_ptz_service() # 获取PTZ配置 ptz_config = ptz_service.GetConfigurationOptions({'ConfigurationToken': media_profile.PTZConfiguration.token})

3.2 基础PTZ控制

PTZ控制主要有两种模式：绝对移动和相对移动。下面是两种模式的实现代码：

绝对移动(指定具体位置)：

def absolute_move(pan, tilt, zoom): request = ptz_service.create_type('AbsoluteMove') request.ProfileToken = media_profile.token request.Position = { 'PanTilt': {'x': pan, 'y': tilt}, 'Zoom': {'x': zoom} } ptz_service.AbsoluteMove(request)

相对移动(指定方向和速度)：

def continuous_move(pan_speed, tilt_speed, zoom_speed, duration=1): request = ptz_service.create_type('ContinuousMove') request.ProfileToken = media_profile.token request.Velocity = { 'PanTilt': {'x': pan_speed, 'y': tilt_speed}, 'Zoom': zoom_speed } ptz_service.ContinuousMove(request) time.sleep(duration) ptz_service.Stop({'ProfileToken': media_profile.token})

3.3 预置点操作

预置点是PTZ控制中非常实用的功能，可以保存和调用常用位置。

# 获取所有预置点 presets = ptz_service.GetPresets({'ProfileToken': media_profile.token}) for preset in presets: print(f"预置点 {preset.token}: {preset.Name}") # 保存当前为预置点 def set_preset(preset_name): request = ptz_service.create_type('SetPreset') request.ProfileToken = media_profile.token request.PresetName = preset_name response = ptz_service.SetPreset(request) return response.PresetToken # 调用预置点 def goto_preset(preset_token): request = ptz_service.create_type('GotoPreset') request.ProfileToken = media_profile.token request.PresetToken = preset_token ptz_service.GotoPreset(request)

4. 图像抓取与配置

虽然ONVIF不直接处理视频流，但我们可以通过它获取静态图像和配置图像参数。

4.1 获取快照

def get_snapshot(save_path='snapshot.jpg'): # 获取快照URI snapshot_uri = media_service.GetSnapshotUri({'ProfileToken': media_profile.token}) # 使用requests获取图像 response = requests.get( snapshot_uri.Uri, auth=requests.auth.HTTPDigestAuth('admin', 'password'), stream=True ) if response.status_code == 200: with open(save_path, 'wb') as f: for chunk in response.iter_content(1024): f.write(chunk) print(f"快照已保存到 {save_path}") else: print(f"获取快照失败: {response.status_code}")

4.2 图像参数配置

我们可以调整摄像头的图像参数，如亮度、对比度等：

def set_image_settings(brightness=None, contrast=None, saturation=None): # 获取当前图像设置 imaging = mycam.create_imaging_service() current_settings = imaging.GetImagingSettings({'VideoSourceToken': media_profile.VideoSourceConfiguration.SourceToken}) # 更新设置 new_settings = current_settings if brightness is not None: new_settings.Brightness = brightness if contrast is not None: new_settings.Contrast = contrast if saturation is not None: new_settings.ColorSaturation = saturation # 应用新设置 imaging.SetImagingSettings({ 'VideoSourceToken': media_profile.VideoSourceConfiguration.SourceToken, 'ImagingSettings': new_settings })

5. 常见问题排查

在实际使用中，难免会遇到各种问题。以下是几个常见问题及其解决方案：

连接失败
- 检查IP地址和端口是否正确
- 确认摄像头已开启ONVIF功能
- 验证用户名和密码是否正确
PTZ命令无响应
- 确认摄像头支持PTZ功能
- 检查ProfileToken是否正确
- 尝试降低移动速度参数
获取快照失败
- 确认快照URI是否正确
- 检查存储路径是否有写入权限
- 尝试使用不同的认证方式
海康摄像头特定问题
- 可能需要启用"匿名登录"选项
- 某些型号需要额外配置ONVIF用户权限
大华摄像头特定问题
- 可能需要手动添加ONVIF用户
- 某些功能可能需要特定固件版本

6. 高级功能与优化

掌握了基础功能后，我们可以进一步探索一些高级应用场景。

6.1 事件订阅与处理

ONVIF支持事件订阅机制，可以实时接收摄像头状态变化：

def setup_event_subscription(): event_service = mycam.create_events_service() # 创建订阅 subscription = event_service.CreatePullPointSubscription() # 定期拉取事件 while True: events = event_service.PullMessages({ 'MessageLimit': 10, 'Timeout': 'PT10S', 'SubscriptionToken': subscription.SubscriptionReference.Address }) for notification in events.NotificationMessage: print(f"事件: {notification.Topic._value_1}") if hasattr(notification, 'Message'): print(f"详情: {notification.Message}") time.sleep(5)

6.2 多摄像头协同控制

在实际项目中，我们经常需要同时控制多个摄像头：

class CameraController: def __init__(self, cameras): self.cameras = cameras self.ptz_services = [cam.create_ptz_service() for cam in cameras] self.profiles = [cam.create_media_service().GetProfiles()[0] for cam in cameras] def sync_move(self, pan_speed, tilt_speed, zoom_speed, duration=1): requests = [] for ptz, profile in zip(self.ptz_services, self.profiles): request = ptz.create_type('ContinuousMove') request.ProfileToken = profile.token request.Velocity = { 'PanTilt': {'x': pan_speed, 'y': tilt_speed}, 'Zoom': zoom_speed } requests.append((ptz, request)) # 同时执行移动命令 for ptz, request in requests: ptz.ContinuousMove(request) time.sleep(duration) # 同时停止 for ptz, profile in zip(self.ptz_services, self.profiles): ptz.Stop({'ProfileToken': profile.token})

6.3 性能优化建议

连接复用：避免频繁创建和销毁服务对象
批量操作：将多个命令合并执行减少网络开销
异常处理：添加完善的错误处理和重试机制
异步处理：考虑使用异步IO提高并发性能

import asyncio from onvif.client import AsyncONVIFCamera async def async_ptz_control(): mycam = AsyncONVIFCamera( '192.168.1.64', 80, 'admin', 'password' ) await mycam.update_xaddrs() media = await mycam.create_media_service() profile = (await media.GetProfiles())[0] ptz = await mycam.create_ptz_service() await ptz.ContinuousMove({ 'ProfileToken': profile.token, 'Velocity': {'PanTilt': {'x': 0.5, 'y': 0}} }) await asyncio.sleep(2) await ptz.Stop({'ProfileToken': profile.token})