云台控制

摄像头云台的控制和图像采集功能。

云台控制

获取云台状态

get_ptzf(timeout=5)

Get current Pan-Tilt-Zoom-Focus values.

Parameters:

timeout (int) – Timeout in seconds (default: 5)

Returns:

云台状态（字段平铺，无嵌套 response 层）

• state: State object with code and describe

• pan: float, 水平角

• tilt: float, 俯仰角

• zoom: float, 变焦倍率

• focus: int, 对焦值

Return type:

GetCurrentPTZFResponse

Examples:

response = get_ptzf()
if response.state.code == 0:
    print(f"Pan: {response.pan}")
    print(f"Tilt: {response.tilt}")

底层 ROS2 接口

• 类型: Service api_msgs/srv/GetPtzfPosition

• 名称: /sdk/cam/get_ptzf_position

• 说明: Request 为空（无请求字段，纯查询）

• 参数映射:

封装参数	原生字段（Request）
timeout	客户端等待时长，不下发

设置云台角度

set_ptzf(pan=0.0, tilt=0.0, zoom=1.0, focus=0, relative=False, timeout=30)

Set Pan-Tilt-Zoom-Focus values for camera control.

Parameters:

• pan (float) – Pan angle in degrees (default: 0.0)

• tilt (float) – Tilt angle in degrees (default: 0.0)

• zoom (float) – Zoom value (default: 1.0)

• focus (int) – Focus value (default: 0)

• relative (bool) – If True, values are relative to current position; if False, absolute (default: False)

• timeout (int) – Timeout in seconds (default: 30)

Return type:

SetPTZFServiceResponse

Returns:

SetPTZFServiceResponse.

Examples:

# Absolute positioning
set_ptzf(pan=45.0, tilt=-30.0, zoom=2.0)

# Relative movement
set_ptzf(pan=10.0, tilt=5.0, relative=True)

底层 ROS2 接口

• 类型: Service cam_msgs/srv/SetPtzfPosition

• 名称: /cam/PTZ_CAM/set_ptzf_position

• 说明: ptzf_position.distance / ptzf_position.fore_ground_focus 由封装保持消息默认值（0 / false），不由调用方指定

• 参数映射:

封装参数	原生字段（Request）
pan	ptzf_position.pan
tilt	ptzf_position.tilt
zoom	ptzf_position.zoom
focus	ptzf_position.focus
relative	relative（false=绝对控制，true=相对控制）
timeout	客户端等待时长，不下发

自动对焦

auto_focus(focus_mode, pixel_bbox, timeout=5)

Trigger one-time auto focus.

Parameters:

• focus_mode (int) – Focus mode. 1 = semi-auto focus, 2 = region focus (requires pixel_bbox).

• pixel_bbox (Bbox) – Target pixel region for region focus mode.

• timeout (int) – Timeout in seconds (default: 5)

Returns:

True if auto focus succeeds, otherwise False.

Return type:

bool

Examples:

bbox = Bbox()
bbox.x_min = 100
bbox.y_min = 80
bbox.x_max = 400
bbox.y_max = 300

auto_focus(focus_mode=1)
auto_focus(focus_mode=2, pixel_bbox=bbox)

底层 ROS2 接口

• 类型: Service cam_msgs/srv/AutoFocus

• 名称: /cam/PTZ_CAM/auto_focus

• 说明: 封装接口返回 bool（即响应的 result 字段）

• 参数映射:

封装参数	原生字段（Request）
focus_mode	focus_mode（1=SEMIAUTO_FOCUS 半自动，2=REGION_AUTO_FOCUS 区域对焦）
pixel_bbox	pixel_bbox（仅 focus_mode=2 区域对焦时需要）
timeout	客户端等待时长，不下发

设置对焦模式

set_focus_mode(focus_mode, timeout=5)

Set camera focus mode.

Parameters:

• focus_mode (int) – Focus mode. Typical values are 1 (semi-auto) or 2 (manual).

• timeout (int) – Timeout in seconds (default: 5)

Returns:

True if the focus mode is set successfully, otherwise False.

Return type:

bool

Examples:

set_focus_mode(focus_mode=1)
set_focus_mode(focus_mode=2, timeout=10)

底层 ROS2 接口

• 类型: Service cam_msgs/srv/SetFocusMode

• 名称: /cam/PTZ_CAM/set_focus_mode

• 说明: 封装接口返回 bool（即响应的 result 字段）

• 参数映射:

封装参数	原生字段（Request）
focus_mode	focus_mode（1=SEMIAUTO 半自动，2=MANUAL 手动）
timeout	客户端等待时长，不下发

云台校准

calibrate_ptz(timeout=30)

Calibrate the PTZ to its zero position.

Parameters:

timeout (int) – Timeout in seconds (default: 30)

Return type:

Trigger_Response

Returns:

Trigger_Response.

Examples:

response = calibrate_ptz()
if response.success:
    print("PTZ calibrated")

底层 ROS2 接口

• 类型: Service std_srvs/srv/Trigger

• 名称: /cam/PTZ_CAM/calibrate_ptz

• 说明: Request 为空（无请求字段，触发式校准回零位）

• 参数映射:

封装参数	原生字段（Request）
timeout	客户端等待时长，不下发

辅助设备控制

set_aux_device(type, device, action, block=True, timeout=30)

Control an auxiliary PTZ device such as light or wiper.

Parameters:

• type (int) – Image channel type. Use 1 for RGB and 2 for infrared.

• device (int) – Target device. Typical values are 1 (light) and 2 (wiper).

• action (int) – Device action. Typical values are 0 (close), 1 (open), 2 (query).

• block (bool) – Whether to block until completion (default: true).

• timeout (int) – Timeout in seconds, only effective when block=false (default: 30).

Returns:

SrvAPISetAuxDevice.Response.

Examples:

set_aux_device(type=1, device=1, action=1)
response = set_aux_device(type=1, device=2, action=2)
if response.result:
    print(response.state)

底层 ROS2 接口

• 类型: Service api_msgs/srv/SetAuxDevice

• 名称: /sdk/cam/set_aux_device

• 参数映射:

封装参数	原生字段（Request）
type	type（1=TYPE_RGB，2=TYPE_INFRARED）
device	device（1=DEVICE_LIGHT 补光灯，2=DEVICE_WIPER 雨刷）
action	action（0=ACTION_CLOSE 关，1=ACTION_OPEN 开，2=ACTION_QUERY 查询）
block	block（true=阻塞直至完成，false=以 timeout 为上限）
timeout	timeout（秒，默认 30，仅 block=false 时生效）

3D 定位

set_3d_location(pixel_bbox, type, disable_autofocus=False, block=True, timeout=30)

Perform 3D localization from a target pixel region.

Parameters:

• pixel_bbox (Bbox) – Target pixel bounding box.

• type (int) – Image type. Use 0 for RGB, 1 for RGB_WITH_ZOOM_IN and 2 for infrared.

• disable_autofocus (bool) – Whether to disable autofocus during localization.

• block (bool) – Whether to block until completion (default: true).

• timeout (int) – Timeout in seconds, only effective when block=false (default: 30).

Returns:

SrvSet3dLocation.Response.

Examples:

bbox = Bbox()
bbox.x_min = 100
bbox.y_min = 80
bbox.x_max = 400
bbox.y_max = 300

response = set_3d_location(bbox, type=0, disable_autofocus=False)
print(response.result)

底层 ROS2 接口

• 类型: Service api_msgs/srv/Set3dLocation

• 名称: /sdk/cam/set_3d_location

• 说明: type 取值 0（RGB）/ 1（RGB_WITH_ZOOM_IN）/ 2（INFRARED），客户端白名单全部放行

• 参数映射:

封装参数	原生字段（Request）
pixel_bbox	pixel_bbox
type	type（0=RGB，1=RGB_WITH_ZOOM_IN，2=INFRARED）
disable_autofocus	disable_autofocus
block	block（true=阻塞直至完成，false=以 timeout 为上限）
timeout	timeout（秒，默认 30，仅 block=false 时生效）

空间引导（ComputePtz）

compute_ptz(x, y, z, zoom, block=True, timeout=30)

Compute PTZ parameters for a target 3D position (space guidance).

Parameters:

• x (float) – Target X coordinate (meters).

• y (float) – Target Y coordinate (meters).

• z (float) – Target Z coordinate (meters).

• zoom (float) – Target zoom level, range [1.0, 25.0].

• block (bool) – Whether to block until completion (default: true).

• timeout (int) – Timeout in seconds, only effective when block=false (default: 30).

Returns:

ComputePtz_Response with .result (bool).

Examples:

response = compute_ptz(x=1.0, y=2.0, z=0.5, zoom=5.0)
print(f"ComputePtz result: {response.result}")

底层 ROS2 接口

• 类型: Service cam_msgs/srv/ComputePtz

• 名称: /cam/PTZ_CAM/compute_ptz

• 参数映射:

封装参数	原生字段（Request）
x / y / z	target_position（geometry_msgs/Point）
zoom	zoom（变焦倍数，范围 [1.0, 25.0]）
block	block（true=阻塞直至完成，false=以 timeout 为上限）
timeout	timeout（秒，默认 30，仅 block=false 时生效）

图像采集

拍摄图片

capture_image(image_name, type='rgb', timeout=15)

Capture an image from the camera.

Parameters:

• image_name (str) – Name for the captured image (required)

• type (str) – Image type - “rgb”, “infra” (default: “rgb”)

• timeout (int) – Timeout in seconds (default: 15)

Return type:

CaptureImageResponse

Returns:

CaptureImageResponse.

Note: Images are saved to /root/data/daystar_api/images/

Examples:

# Capture RGB image
response = capture_image("photo_001")
if response.response.success:
    print(f"Image captured: {response.response.message}")

# Capture infrared image
capture_image("infra_001", type="infra")

底层 ROS2 接口

• 类型: Service cam_msgs/srv/CaptureImage

• 名称: /cam/PTZ_CAM/capture_image

• 参数映射:

封装参数	原生字段（Request）
image_name	save_path（客户端拼接为 /root/data/daystar_api/images/<image_name>.jpeg）
type	type（客户端换算：”rgb” → 1，”infra” → 2）
timeout	客户端等待时长，不下发

抓取压缩图像数据

capture_raw_image(type, timeout=5)

Capture compressed image data directly without saving to disk.

Parameters:

• type (int) – Image type. Use 1 for RGB and 2 for infrared.

• timeout (int) – Timeout in seconds (default: 5)

Return type:

CaptureRawImage_Response

Returns:

CaptureRawImage_Response.

Examples:

response = capture_raw_image(type=1)
if response.result:
    print(response.format)

底层 ROS2 接口

• 类型: Service cam_msgs/srv/CaptureRawImage

• 名称: /cam/PTZ_CAM/capture_raw_image

• 说明: 不落盘。响应在绑定层转换为 CaptureRawImage_Response： 底层 image（sensor_msgs/CompressedImage）的 data 经 base64 编码 为字符串、format 原样透传，result 透传

• 参数映射:

封装参数	原生字段（Request）
type	type（1=RGB，2=INFRARED）
timeout	客户端等待时长，不下发

录制视频

capture_video(type, record_time, video_name, timeout=5)

Record a video to /root/data/daystar_api/videos/<video_name>.mp4.

Parameters:

• type (int) – Image type. Use 1 for RGB and 2 for infrared.

• record_time (int) – Record duration in seconds. Use 0 for toggle mode.

• video_name (str) – Video name (without extension). The file is saved as /root/data/daystar_api/videos/<video_name>.mp4.

• timeout (int) – Timeout in seconds (default: 5)

Return type:

CaptureVideo_Response

Returns:

SrvCaptureVideo.Response.

Examples:

capture_video(type=1, record_time=10, video_name="patrol_001")

底层 ROS2 接口

• 类型: Service cam_msgs/srv/CaptureVideo

• 名称: /cam/PTZ_CAM/capture_video

• 参数映射:

封装参数	原生字段（Request）
type	type（1=TYPE_RGB，2=TYPE_INFRARED）
record_time	record_time（录制秒数；0=开始/结束切换模式）
video_name	save_path（客户端拼接为 /root/data/daystar_api/videos/<video_name>.mp4）
timeout	客户端等待时长，不下发

获取已保存图片

get_available_images(timeout=30)

Get list of all captured images.

Parameters:

timeout (int) – Timeout in seconds (default: 30)

Return type:

GetAvailableImagesResponse

Returns:

GetAvailableImagesResponse.

Note: Images are stored in /root/data/daystar_api/images/

Examples:

response = get_available_images()
if response.response.success:
    for img_name in response.response.image_names:
        print(f"Image: {img_name}")

底层 ROS2 接口

本接口不经 ROS2 通道（纯本地实现：递归枚举 /root/data/daystar_api/images/ 目录下的文件，返回去扩展名的相对路径名；timeout 参数实际未使用）。

删除图片

delete_image(image_name)

Delete a captured image by name.

删除指定名称的已抓拍云台照片（删除图像文件，不可恢复）。名称用 get_available_images 返回的名称（不含扩展名）。照片存于 /root/data/daystar_api/images/。

Parameters:

image_name (str) – 要删除的照片名称（不含扩展名；禁止绝对路径/反斜杠/..）

Returns:

删除结果

• state: 状态（state.code==0 成功）

• result: bool，是否成功删除

Return type:

DeleteImageResponse

Note: Images are stored in /root/data/daystar_api/images/

Examples:

# 删除单张照片
result = delete_image("snap_001")
if result.result:
    print("照片已删除")

# 配合 get_available_images 批量删除
response = get_available_images()
for img_name in response.response.image_names:
    delete_image(img_name)

底层 ROS2 接口

本接口不经 ROS2 通道（纯本地实现：删除 /root/data/daystar_api/images/<image_name>.jpeg，不存在时回退按原样名删除）。

批量删除图片

delete_images(image_names=[], delete_all=False)

Batch-delete captured images.

批量删除已抓拍云台照片。传 image_names 列表删除指定照片（单元素=指定，多元素=批量）； delete_all=True 时忽略 image_names，快速删除全部已抓拍照片。名称用 get_available_images 返回的名称（不含扩展名）。删除不可恢复。

Parameters:

• image_names (list[str]) – 要删除的照片名称列表（delete_all=True 时可省略）

• delete_all (bool) – 为 True 时删除全部照片，默认 False

Returns:

批量删除结果

• result: bool，是否全部成功

• deleted: list[str]，成功删除的名称

• failed: list[str]，删除失败的名称

Return type:

DeleteImagesResponse

Note: Images are stored in /root/data/daystar_api/images/

Examples:

# 删除指定若干照片
delete_images(["snap_001", "snap_002"])

# 快速删除全部照片
delete_images(delete_all=True)

底层 ROS2 接口

本接口不经 ROS2 通道（纯本地实现：逐个调用单张删除逻辑删本地文件；delete_all=True 时递归枚举 /root/data/daystar_api/images/ 目录得到目标列表）。

获取已保存视频

get_available_videos(timeout=5)

Get list of all saved videos.

Parameters:

timeout (int) – Timeout in seconds (default: 5)

Return type:

GetAvailableVideosResponse

Returns:

GetAvailableVideosResponse.

Note: Videos are stored in /root/data/daystar_api/videos/

Examples:

response = get_available_videos()
if response.response.success:
    for video_name in response.response.video_names:
        print(f"Video: {video_name}")

底层 ROS2 接口

本接口不经 ROS2 通道（纯本地实现：递归枚举 /root/data/daystar_api/videos/ 目录下的文件，返回去扩展名的相对路径名；timeout 参数实际未使用）。

目标区域检测（ROI Detection）

find_roi(template_bbox, template_image_name, initial_focus_value, final_focus_value, final_zoom, detect_algorithm, algorithm_param='', object_name='', timeout=300)

Perform ROI detection using the camera.

Parameters:

• template_bbox (Bbox) – Target region bounding box (x_min, y_min, x_max, y_max).

• template_image_name (str) – Template image name (without extension). The file is loaded from /root/data/daystar_api/ptz_templates/<template_image_name>.jpeg.

• initial_focus_value (int) – Starting focus value.

• final_focus_value (int) – Ending focus value.

• final_zoom (float) – Final zoom level.

• detect_algorithm (int) – 1=FEATURE_MATCHING, 2=KNIFE_GATE_RECOGNITION, 3=POWER_MODEL_DETECTION, 5=INFRARED_RECOGNITION, 6=POWER_MODEL_MULTI_DETECTION.

• algorithm_param (str) – Algorithm parameters (JSON, default empty).

• object_name (str) – Target object name (default empty).

• timeout (int) – Timeout in seconds (default 300).

Return type:

FindRoiResult

Returns:

FindRoiResult with .result (bool).

Examples:

bbox = Bbox()
bbox.x_min, bbox.y_min = 100, 80
bbox.x_max, bbox.y_max = 400, 300
result = find_roi(bbox, "template_001",
                  initial_focus_value=100, final_focus_value=200,
                  final_zoom=2.0, detect_algorithm=1)
print(f"FindRoi: {result.result}")

底层 ROS2 接口

• 类型: Action cam_msgs/action/FindRoi

• 名称: /cam/PTZ_CAM/find_roi

• 说明: 通过 ROS2 Action 调用，feedback（string status）通过 /sdk/cam/find_roi_feedback topic 发布

• 参数映射:

封装参数	原生字段（Goal）
template_bbox	`template_bbox`（cam_msgs/Bbox，像素坐标）
template_image_name	template_image_path（客户端拼接为 /root/data/daystar_api/ptz_templates/<template_image_name>.jpeg）
initial_focus_value / final_focus_value	initial_focus_value / final_focus_value
final_zoom	final_zoom
detect_algorithm	`detect_algorithm`（1=特征匹配，2=刀闸识别，3=电力模型检测，5=红外识别，6=电力模型多目标检测）
algorithm_param / object_name	algorithm_param / object_name
timeout	客户端等待时长，不下发

相关数据类型

云台/相机相关的响应类型详细说明请参见 数据结构 文档：

接口层响应:

• GetCurrentPTZFResponse - 获取云台状态响应

• SetPTZFServiceResponse - 设置云台角度响应

• CaptureImageResponse - 拍摄图片响应

• GetAvailableImagesResponse - 获取图片列表响应

• GetAvailableVideosResponse - 获取视频列表响应

ROS 层响应:

• Trigger_Response - 通用触发响应（calibrate_ptz 返回）

• SetAuxDevice_Response - 辅助设备控制响应（set_aux_device 返回）

• Set3dLocation_Response - 3D 定位响应（set_3d_location 返回）

• CaptureRawImage_Response - 压缩图像数据响应（capture_raw_image 返回，data 为 base64 字符串）

• CaptureVideo_Response - 录制视频响应（capture_video 返回）