多媒体服务接口

云台视频流服务

硬件

晨星机器狗的云台摄像机可同时提供可见光和红外视频流，如下所示：

软件接口

云台摄像机的视频流可通过标准 RTSP API 网络接口访问。

可见光视频流URL: rtsp://admin:yoseen2018@192.168.144.202:554/h264/ch1/sub/av_stream
红外视频流URL: rtsp://admin:yoseen2018@192.168.144.202:554/h264/ch2/sub/av_stream

注意事项

开发设备需连接机器狗的网络（WiFi 名称：IS_**，WiFi 密码：DaystarBot）以访问视频流。
相机流 URL 应根据机器狗的 IP 地址进行调整：
- 连接到机器狗的网络后，检查机器狗的 IP 是否为 192.168.144.*
  - 如果网段为 144, 则在流 URL 中使用 192.168.144.202

视频流验证与测试

你可以使用 VLC 媒体播放器来连接和显示视频流。

可见光视频流：

红外视频流：

功能	C++	ROS	Python	C#	Java
获取云台姿态信息	✔	✔	✔	✔	✔
控制云台运动角度	✔	✔	✔	✔	✔
控制云台持续运动	✔	✔	✔	✔	✔
辅助聚焦	✔	✔	✔	✔	✔
切换对焦模式	✔	✔	✔	✔	✔
灯光控制	✔	✔	✔	✔	✔
云台拍照	✔	-	✔	✔	✔
下载图片	✔	-	✔	✔	✔

云台控制接口

获取云台姿态信息

该接口用于发布云台的当前位姿信息。

参数名称	类型	描述
`pan`	`float32`	表示pan的旋转 (`-180`~`180`)
`tilt`	`float32`	表示tilt的旋转(`-90`~`90`)
`zoom`	`float32`	表示zoom的缩放(`1`-`25`)
`focus`	`uint16`	表示对焦值(`4000`~`40000`)

ROS2 接口

Topic 名称	Topic 类型	角色
`cam/PTZ_CAM/set_ptzf_position`	`cam_msgs::msg::PtzfPosition`	订阅方

消息结构

ptzf_position: PtzfPosition类型，包含四个类型：

参数名称	类型	描述
`pan`	`float32`	表示pan的旋转 (`-180`~`180`)
`tilt`	`float32`	表示tilt的旋转(`-90`~`90`)
`zoom`	`float32`	表示zoom的缩放(`1`-`25`)
`focus`	`uint16`	表示对焦值(`4000`~`40000`)

测试方法

bash

ros2 topic echo /cam/PTZ_CAM/set_ptzf_position

Python 接口

`subscribe_ptzf_position(ptzf_position_callback)`

功能说明
订阅云台的实时位置信息，包括水平角度(pan)、垂直角度(tilt)、变焦(zoom)和焦点(focus)参数。

参数说明

参数名	类型	必填/默认值	说明
`ptzf_position_callback`	`function`	必填	实时接收点云状态信息的回调函数。

返回值

类型	说明
`void`	无返回值。

使用案例

python

def on_ptz_pos(data):
    if "ptzf_position" in data:
        pos = data["ptzf_position"]
        print(f"PTZ位置: P={pos.get('pan'):.2f}, T={pos.get('tilt'):.2f}, Z={pos.get('zoom'):.2f}")

client.subscribe_ptzf_position(on_ptz_pos)

`unsubscribe_ptzf_position()`

功能说明
取消订阅云台的实时位置信息。

参数说明
无。

返回值

类型	说明
`void`	无返回值。

使用案例

cpp

client.unsubscribe_ptzf_position();

C# 接口

`void SubscribePtzPosition(Action<PtzPositionStamped> callback = null)`

功能说明
订阅云台的实时位置信息，包括水平角度(pan)、垂直角度(tilt)、变焦(zoom)和焦点(focus)参数。

参数说明

参数名	类型	必填/默认值	说明
`callback`	`Action<PtzPositionStamped>`	`null`	接收位置数据的回调函数。

返回值

类型	说明
`void`	无返回值。

`void UnsubscribePtzPosition()`

功能说明
取消订阅云台的实时位置信息。

参数说明
无。

返回值

类型	说明
`void`	无返回值。

使用案例

csharp

private RobotSDKManager _robotSDKManager;
private RobotMutiMediaClient _robotMutiMediaClient;

_robotMutiMediaClient = _robotSDKManager.CreateRobotMutiMediaClient();

// 订阅ptz位置信息
_robotMutiMediaClient?.SubscribePtzPosition(OnPtzPositionReceived);

// 回调函数处理位置数据
private void OnPtzPositionReceived(PtzPositionStamped positionData)
{
    Debug.Log($"ptz Position - Pan: {positionData.position.pan}, " +
              $"Tilt: {positionData.position.tilt}, " +
              $"Zoom: {positionData.position.zoom}, " +
              $"Focus: {positionData.position.focus}");
}

// 取消订阅ptz位置信息
_robotMutiMediaClient?.UnsubscribePtzPosition();

C++ 接口

`bool subscribePtzfPosition()`

功能说明
订阅云台的实时位置信息，包括水平角度(pan)、垂直角度(tilt)、变焦(zoom)和焦点(focus)参数。

参数说明
无。

返回值

类型	说明
`bool`	`true`表示成功，`false`表示失败。

`bool unsubscribePtzfPosition()`

功能说明
取消订阅云台的实时位置信息。

参数说明
无。

返回值

类型	说明
`bool`	`true`表示成功，`false`表示失败。

使用案例

cpp

Lenovo::Daystar::SDK sdk;
auto &sysb = sdk.getSYSB();

if (sysb.connect()) {
    // 订阅位置消息
    sysb.subscribePtzfPosition();
    
    // 执行一些操作...
    std::this_thread::sleep_for(std::chrono::seconds(10));
    
    // 取消订阅
    if (sysb.unsubscribePtzfPosition()) {
        std::cout << "云台位置订阅已取消" << std::endl;
    }
}

Java 接口

`void SubscribesysbfPosition(Consumer<Object> callback)`

功能说明
订阅云台的实时位置信息。

参数说明

参数名	类型	必填/默认值	说明
`callback`	`Consumer<Object>`	必填	接收位置数据的回调函数。

返回值

类型	说明
`void`	无返回值。

使用案例

java

client.SubscribesysbfPosition(data -> {
    System.out.println("PTZF Data: " + data);
});

控制云台运动角度

该接口用于使调用云台移动到某个角度。

注意：云台功能设计中 zoom 参数始终为绝对值，不受 relative 参数影响。

ROS2 接口

Service 名称	Service 类型	角色
`/cam/PTZ_CAM/set_ptzf_position`	`cam_msgs::srv::SetPtzfPosition`	客户端

消息结构

cam_msgs::srv::SetPtzfPosition::Request 包括以下字段：

参数名称	类型	描述
`relative`	`bool`	表示是否启用相对移动
`ptzf_position`	`PtzfPosition`	包含四个字段：`pan`, `tilt`, `zoom`, `focus`

ptzf_position 字段：

字段名称	类型	描述
`pan`	`float32`	表示pan的旋转 (`-180`~`180`)
`tilt`	`float32`	表示tilt的旋转(`-90`~`90`)
`zoom`	`float32`	表示zoom的缩放(`1`-`25`)
`focus`	`uint16`	表示对焦值(`4000`~`40000`)

注：focus字段仅在手动对焦模式生效。

测试方法

调用接口，使云台左转90度，上转30度，并放大到10倍：

bash

ros2 service call /cam/PTZ_CAM/set_ptzf_position cam_msgs/srv/SetPtzfPosition "relative: false
ptzf_position:
  pan: 90.0
  tilt: 30.0
  zoom: 10.0
  focus: 0"

Python 接口

`set_ptzf_position(position: PtzfPosition, relative)`

功能说明
控制云台移动到某个角度。

参数说明

参数名	类型	必填/默认值	说明
`position`	`PtzfPosition`	必填	角度指令，说明参考ROS2接口。
`relative`	`bool`	必填	表示是否启用相对移动。

返回值

类型	说明
`bool`	操作是否成功。

使用案例

python

async with WebSocketRobotClient(host=args.host, port=args.port) as client:
    await asyncio.sleep(1)
    position = PtzfPosition(
        pan=args.pan,
        tilt=args.tilt,
        zoom=args.zoom,
        focus=args.focus
    )
    success = await client.set_ptzf_position(position, relative=args.relative)

C# 接口

`void SetPtzPosition(float pan, float tilt, float zoom, ushort focus, bool relative = false)`

功能说明
控制云台移动到某个角度。

参数说明

参数名	类型	必填/默认值	说明
`pan`	`float`	必填	水平角度 (度)。
`tilt`	`float`	必填	垂直角度 (度)。
`zoom`	`float`	必填	变焦倍数。
`focus`	`ushort`	必填	聚焦值。
`relative`	`bool`	`false`	是否为相对位置 (`true`=相对，`false`=绝对)。

返回值

类型	说明
`void`	无返回值。

使用案例

csharp

private RobotSDKManager _robotSDKManager;
private RobotMutiMediaClient _robotMutiMediaClient;

_robotMutiMediaClient = _robotSDKManager.CreateRobotMutiMediaClient();

// 绝对位置控制
robotMutiMediaClient.SetPtzPosition(45.0f, -30.0f, 2.0f, 0, false);

// 相对位置控制（在当前位置基础上调整）
robotMutiMediaClient.SetPtzPosition(10.0f, 0, 0, 0, true);

C++ 接口

`void callPTZPosition(float pan, float tilt, float zoom, uint16_t focus, bool relative = false)`

功能说明
控制云台到指定位置。

参数说明

参数名	类型	必填/默认值	说明
`pan`	`float`	必填	水平角度 (度)。
`tilt`	`float`	必填	垂直角度 (度)。
`zoom`	`float`	必填	变焦倍数。
`focus`	`uint16_t`	必填	聚焦值。
`relative`	`bool`	`false`	是否为相对位置 (`true`=相对，`false`=绝对)。

返回值

类型	说明
`void`	无返回值。

使用案例

cpp

Lenovo::Daystar::SDK sdk;
auto &sysb = sdk.getSYSB();

if (sysb.connect()) {
    // 绝对位置控制：云台转到水平30度，垂直15度
    sysb.callPTZPosition(30.0f, 15.0f, 1.5f, 100, false);
    
    // 相对位置控制：在当前位置基础上水平右转10度
    sysb.callPTZPosition(10.0f, 0.0f, 1.0f, 100, true);
}

Java 接口

`void SetsysbPosition(PtzPosition position)`

功能说明
控制云台移动到某个角度。

参数说明

参数名	类型	必填/默认值	说明
`position`	`PtzPosition`	必填	云台位置对象。

返回值

类型	说明
`void`	无返回值。

使用案例

java

PtzPosition pos = new PtzPosition();
pos.pan = 10.0f;
pos.tilt = 5.0f;
pos.zoom = 1.0f;
pos.focus = 0;
client.SetsysbPosition(pos);

控制云台持续运动

该接口用于使调用云台持续移动。

该接口涉及四个参数：

参数名称	类型	描述
`pan`	`float32`	水平方向速度值，正值逆时针转，负值顺时针转，0不转 (`-12`~`12`)
`tilt`	`float32`	垂直方向速度值，正值向上转，负值向下转，0不转(`-12`~`12`)
`zoom`	`float32`	缩放速度值，正值放大，负值缩小，0不动 (`-12`~`12`)
`focus`	`uint16`	对焦速度值，正值推远焦，负值拉近焦，0不动(`-12`~`12`)

注意：控制上下左右持续运动时，zoom和focus参数必须设置为0.

ROS2 接口

Topic 名称	Topic 类型	角色
`/cam/PTZ_CAM/ptzf_cmd_vel`	`cam_msgs::srv::PtzfCmdVel`	客户端

消息结构

cam_msgs::srv::PtzfCmdVel::Request 包括以下字段：

参数名称	类型
`pan`	`float32`
`tilt`	`float32`
`zoom`	`float32`
`focus`	`uint16`

测试方法

调用接口，云台开始左转：

bash

ros2 topic pub /cam/PTZ_CAM/ptzf_cmd_vel cam_msgs/srv/PtzfCmdVel "
  pan: 8.0
  tilt: 0.0
  zoom: 0.0
  focus: 0"

Python 接口

`publish_ptzf_cmd_vel(cmd_vel: PtzfCmdVel)`

功能说明
持续控制云台运动。

参数说明

参数名	类型	必填/默认值	说明
`cmd_vel`	`PtzfCmdVel`	必填	速度指令对象。

PtzfCmdVel 类说明

字段名	类型	默认值	说明
`pan`	`float`	`0.0`	水平方向速度值，正值逆时针转，负值顺时针转，0不转 (-12~12)
`tilt`	`float`	`0.0`	垂直方向速度值，正值向上转，负值向下转，0不转（-12~12）
`zoom`	`float`	`0.0`	缩放速度值，正值放大，负值缩小，0不动（-12~12）
`focus`	`float`	`0.0`	对焦速度值，正值推远焦，负值拉近焦，0不动（-12~12）

使用案例

python

async with WebSocketRobotClient(host=args.host, port=args.port, client_name="complex_control") as client:
    await asyncio.sleep(1)
    await client.advertise_ptzf_cmd_vel()
    await asyncio.sleep(0.5)
    cmd_vel = PtzfCmdVel(
        pan=args.pan,
        tilt=args.tilt, 
        zoom=args.zoom,
        focus=args.focus
    )
    print(f"复合运动控制: Pan={args.pan}, Tilt={args.tilt}, Zoom={args.zoom}, Focus={args.focus}")
    success = await client.publish_ptzf_cmd_vel(cmd_vel)

C# 接口

`void MovePtzContinues(float panSpeed, float tiltSpeed, float zoomSpeed, float focusSpeed = 0)`

功能说明
持续控制云台运动。

参数说明

字段名	类型	默认值	说明
`pan`	`float`	`0.0`	水平方向速度值，正值逆时针转，负值顺时针转，0不转 (-12~12)
`tilt`	`float`	`0.0`	垂直方向速度值，正值向上转，负值向下转，0不转（-12~12）
`zoom`	`float`	`0.0`	缩放速度值，正值放大，负值缩小，0不动（-12~12）
`focus`	`float`	`0.0`	对焦速度值，正值推远焦，负值拉近焦，0不动（-12~12）

返回值

类型	说明
`void`	无返回值。

使用案例

csharp

private RobotSDKManager _robotSDKManager;
private RobotMutiMediaClient _robotMutiMediaClient;

_robotMutiMediaClient = _robotSDKManager.CreateRobotMutiMediaClient();

// 向左连续移动
robotMutiMediaClient.MovePtzContinues(8.0f, 0, 0, 0);
// 向右连续移动
robotMutiMediaClient.MovePtzContinues(-8.0f, 0, 0, 0);

// 向上连续移动
robotMutiMediaClient.MovePtzContinues(0, 8.0f, 0, 0);
// 向下连续移动
robotMutiMediaClient.MovePtzContinues(0, -8.0f, 0, 0);

// 放大（变焦）
robotMutiMediaClient.MovePtzContinues(0, 0, 1.0f, 0);
// 缩小（变焦）
robotMutiMediaClient.MovePtzContinues(0, 0, -1.0f, 0);

// 停止移动
robotMutiMediaClient.MovePtzContinues(0, 0, 0, 0);

C++ 接口

`void publishPtzfCmdVel(float pan, float tilt, float zoom, float focus)`

功能说明
持续控制云台运动。

参数说明

参数名	类型	必填/默认值	说明
`pan`	`float`	必填	水平旋转速度。
`tilt`	`float`	必填	垂直旋转速度。
`zoom`	`float`	必填	变焦速度。
`focus`	`float`	必填	聚焦速度。

返回值

类型	说明
`void`	无返回值。

使用案例

cpp

Lenovo::Daystar::SDK sdk;
auto &sysb = sdk.getSYSB();

if (sysb.connect()) {
    // 以中等速度向右旋转
    for (int i = 0; i < 40; i++)
    {
        sysb.publishPtzfCmdVel(0.8f, 0.0f, 0.0f, 0.0f);
        // std::cout << "发送第 " << (i + 1) << "/40 次速度控制命令" << std::endl;
        std::this_thread::sleep_for(std::chrono::milliseconds(50));
    }

    std::this_thread::sleep_for(std::chrono::seconds(2));
    
    // 停止所有运动
    sysb.stopAllMovement();
}

Java 接口

`void MovesysbContinues(PtzPosition position)`

功能说明
持续控制云台运动。

参数说明

参数名	类型	必填/默认值	说明
`position`	`PtzPosition`	必填	使用PtzPosition结构传递速度信息 (pan, tilt, zoom, focus)。

返回值

类型	说明
`void`	无返回值。

使用案例

java

PtzPosition speed = new PtzPosition();
speed.pan = 5.0f; // Speed
client.MovesysbContinues(speed);

辅助聚焦

ROS2 接口

该接口用于使调用云台移动到某个角度。

Topic 名称	Topic 类型	角色
`/cam/PTZ_CAM/auto_focus`	`cam_msgs::srv::AutoFocus`	客户端

消息结构

cam_msgs::srv::AutoFocus::Request 包括以下字段：

参数名称	类型	描述
`focus_mode`	`uint8`	`1`: 全局辅助聚焦 `2`: 区域辅助聚焦
`pixel_bbox`	`Bbox`	包含四个字段：`x_min`, `y_min`, `x_max`, `y_max`

pixel_bbox 字段：

字段名称	类型	描述
`x_min`	`int32`	矩形区域左上顶点的x坐标
`y_min`	`int32`	矩形区域左上顶点的y坐标
`x_max`	`int32`	矩形区域右下顶点的x坐标
`y_max`	`int32`	矩形区域右下顶点的y坐标

注：pixel_bbox只有区域辅助聚焦时有效

测试方法

调用接口，调一次切换起立/坐下状态：

bash

ros2 service call /cam/PTZ_CAM/auto_focus cam_msgs/srv/AutoFocus "focus_mode: 2
pixel_bbox:
  x_min: 500
  y_min: 300
  x_max: 1600
  y_max: 900"

Python 接口

`auto_focus(focus_mode, pixel_bbox=None)`

功能说明
实现云台聚焦功能。

参数说明

参数名	类型	必填/默认值	说明
`focus_mode`	`int`	必填	1: 表示全局辅助聚焦; 2: 表示区域辅助聚焦
`pixel_bbox`	`dict`	`None`	聚焦区域设置(参考ros2接口说明)

返回值

类型	说明
`bool`	执行结果，True表示成功

使用案例

python

async with WebSocketPtzClient(host=args.host, port=args.port) as client:
        await asyncio.sleep(1)
        if args.mode == 1:
            success = await client.auto_focus(focus_mode=1)
        elif args.mode == 2:
            if hasattr(args, 'bbox') and args.bbox:
                try:
                    coords = [int(x.strip()) for x in args.bbox.split(',')]
                    bbox = {
                        "x_min": coords[0],
                        "y_min": coords[1], 
                        "x_max": coords[2],
                        "y_max": coords[3]
                    }
                    success = await client.auto_focus(focus_mode=2, pixel_bbox=bbox)

C#接口

`bool AutoFocus(int focusMode = 1, PixelBoundingBox? pixelBbox = null, int timeoutMs = 8000)`

功能说明
启用自动聚焦。

参数说明

参数名	类型	必填/默认值	说明
`focusMode`	`int`	必填	1=全局辅助聚焦, 2=区域辅助聚焦
`boundingBox`	`PixelBoundingBox`	选填	聚焦区域 (仅模式2有效)

返回值

类型	说明
`bool`	`true` 成功，`false` 失败。

使用案例

csharp

private RobotSDKManager _robotSDKManager;
private RobotMutiMediaClient _robotMutiMediaClient;

_robotMutiMediaClient = _robotSDKManager.CreateRobotMutiMediaClient();

// 半自动对焦
bool success = _robotMutiMediaClient?.AutoFocus(1) ?? false;

// 区域对焦（使用默认中心区域）
bool success = _robotMutiMediaClient?.AutoFocus(2) ?? false;

// 区域对焦（自定义区域）
PixelBoundingBox customRegion = new PixelBoundingBox
{
    x_min = 100, y_min = 100,
    x_max = 300, y_max = 300
};
bool success = _robotMutiMediaClient?.AutoFocus(2, customRegion) ?? false;

C++ 接口

`bool autoFocus(int focus_mode = 1)`

功能说明
启用自动聚焦。

参数说明

参数名	类型	必填/默认值	说明
`focus_mode`	`int`	`1`	聚焦模式 (1=自动聚焦)。

返回值

类型	说明
`bool`	`true` 成功，`false` 失败。

使用案例

cpp

Lenovo::Daystar::SDK sdk("192.168.100.103:50051");
auto &sysb = sdk.getSYSB();

if (sysb.connect()) {
    if (sysb.autoFocus(1)) {
        std::cout << "自动聚焦启用成功" << std::endl;
    } else {
        std::cerr << "自动聚焦启用失败" << std::endl;
    }
}

Java 接口

`void AutoFocus(int focusMode, PixelBoundingBox boundingBox)`

功能说明
实现云台聚焦功能。

参数说明

参数名	类型	必填/默认值	说明
`focusMode`	`int`	必填	1=全局辅助聚焦, 2=区域辅助聚焦
`boundingBox`	`PixelBoundingBox`	选填	聚焦区域 (仅模式2有效)

返回值

类型	说明
`void`	无返回值。

使用案例

java

client.AutoFocus(1, null);

切换对焦模式

ROS2 接口

该接口用于使调用云台移动到某个角度。

Service名称	Service类型	描述
`/cam/PTZ_CAM/set_focus_mode`	`cam_msgs::srv::SetFocusMode`	客户端

消息结构

cam_msgs::srv::SetFocusMode::Request 包括以下字段：

参数名称	类型	描述
`focus_mode`	`uint8`	`1`: 半自动对焦 `2`: 手动对焦

测试方法

bash

ros2 service call /cam/PTZ_CAM/set_focus_mode cam_msgs/srv/SetFocusMode "focus_mode: 2"

Python 接口

`set_focus_mode(focus_mode)`

功能说明
实现云台聚焦模式的设定。

参数说明

参数名	类型	必填/默认值	说明
`focus_mode`	`int`	必填	1: 表示半自动对焦; 2: 表示手动对焦

返回值

类型	说明
`bool`	执行结果，True表示成功

使用案例

python

async with WebSocketPtzClient(host=args.host, port=args.port, client_name="focus_mode_control") as client:
    await asyncio.sleep(1)
    # 设置为半自动对焦
    await client.set_focus_mode(1)
    # 设置为手动对焦
    await client.set_focus_mode(2)

C#接口

`bool SetFocusMode(int focusMode, int timeoutMs = 8000)`

功能说明
设置对焦模式。

参数说明

参数名	类型	必填/默认值	说明
`focusMode`	`int`	必填	1: 表示半自动对焦; 2: 表示手动对焦
`timeoutMs`	`int`	`默认值：8000`	超时时间(毫秒)

返回值

类型	说明
`bool`	执行结果，`true`表示成功，`false`表示失败

使用案例

csharp

private RobotSDKManager _robotSDKManager;
private RobotMutiMediaClient _robotMutiMediaClient;

_robotMutiMediaClient = _robotSDKManager.CreateRobotMutiMediaClient();

// 设置为半自动对焦模式
bool success = _robotMutiMediaClient?.SetFocusMode(1) ?? false;

// 设置为手动对焦模式
bool success = _robotMutiMediaClient?.SetFocusMode(2) ?? false;

C++ 接口

`bool setFocusMode(int focus_mode)`

功能说明
设置聚焦模式。

参数说明

参数名	类型	必填/默认值	说明
`focus_mode`	`int`	必填	聚焦模式。

返回值

类型	说明
`bool`	`true` 成功，`false` 失败。

使用案例

cpp

Lenovo::Daystar::SDK sdk;
auto &sysb = sdk.getSYSB();

if (sysb.connect()) {
    if (sysb.setFocusMode(2)) {
        std::cout << "聚焦模式设置成功" << std::endl;
    } else {
        std::cerr << "聚焦模式设置失败" << std::endl;
    }
}

Java 接口

`void SetFocusMode(int focusMode)`

功能说明
设置对焦模式。

参数说明

参数名	类型	必填/默认值	说明
`focusMode`	`int`	必填	1=半自动, 2=手动

返回值

类型	说明
`void`	无返回值。

使用案例

java

client.SetFocusMode(1);

灯光控制

ROS2 接口

该接口用于使调用云台移动到某个角度。

Service 名称	Service 类型	角色
`/cam/PTZ_CAM/light_cmd`	`cam_msgs::srv::SetBool`	客户端

消息结构

cam_msgs::srv::SetBool::Request 包括以下字段：

值	描述
`1`	表示开灯
`0`	表示关灯

测试方法

调用接口，调一次切换起立/坐下状态：

bash

ros2 service call /cam/PTZ_CAM/light_cmd cam_msgs/srv/SetBool "focus_mode: 2"

Python 接口

`light_cmd(enable)`

功能说明
实现云台灯光设定。

参数说明

参数名	类型	必填/默认值	说明
`enable`	`bool`	必填	1: 表示开灯; 0: 表示关灯

返回值

类型	说明
`bool`	执行结果，True表示成功

使用案例

python

async with WebSocketPtzClient(host=args.host, port=args.port, client_name="light_control") as client:
        await asyncio.sleep(1)
        action_str = "开启" if args.enable else "关闭"
        print(f"{action_str}云台灯光...")
        success = await client.light_cmd(args.enable)

C#接口

`void SetPtzLight(bool enable)`

功能说明
设置云台补光灯状态。

参数说明

参数名	类型	必填/默认值	说明
`enable`	`bool`	必填	`true`: 开启; `false`: 关闭

返回值

类型	说明
`void`	无返回值

使用案例

csharp

private RobotSDKManager _robotSDKManager;
private RobotMutiMediaClient _robotMutiMediaClient;

_robotMutiMediaClient = _robotSDKManager.CreateRobotMutiMediaClient();

// 开启PTZ灯光
robotMutiMediaClient.SetPtzLight(true);
// 关闭PTZ灯光
robotMutiMediaClient.SetPtzLight(false);

Java 接口

`void LightCmd(boolean enable)`

功能说明
实现云台灯光设定。

参数说明

参数名	类型	必填/默认值	说明
`enable`	`boolean`	必填	true=开, false=关

返回值

类型	说明
`void`	无返回值。

使用案例

java

client.LightCmd(true);

C++ 接口

`bool lightCmd(bool enable)`

功能说明
控制补光灯。

参数说明

参数名	类型	必填/默认值	说明
`enable`	`bool`	必填	`true` 开启补光灯，`false` 关闭补光灯。

返回值

类型	说明
`bool`	`true` 成功，`false` 失败。

使用案例

cpp

Lenovo::Daystar::SDK sdk("192.168.144.103:50051");
auto &sysb = sdk.getSYSB();

if (sysb.connect()) {
    // 开启补光灯
    if (sysb.lightCmd(true)) {
        std::cout << "补光灯已开启" << std::endl;
    }
    
    std::this_thread::sleep_for(std::chrono::seconds(5));
    
    // 关闭补光灯
    if (sysb.lightCmd(false)) {
        std::cout << "补光灯已关闭" << std::endl;
    }
}

云台拍照

Python 接口

`async def capture_image(image_type: str = "rgb", image_name: str = "") -> dict`

功能说明
控制云台相机拍摄照片。

参数说明

参数名	类型	必填/默认值	说明
`image_type`	`str`	`rgb`	图片类型 ("rgb" 或 "infra")
`image_name`	`str`	选填	图片名称（不含扩展名），为空则自动生成

返回值

类型	说明
`dict`	包含 success(bool) 和 message(str)

调用示例

python

await client.capture_image("rgb", "my_photo")

C# 接口

`(bool success, string message) CaptureImage(string type, string imageName, int timeoutMs = 10000)`

功能说明
控制云台相机拍摄照片。

参数说明

参数名	类型	必填/默认值	说明
`type`	`string`	必填	图片类型 ("rgb" 或 "infra")
`imageName`	`string`	必填	图片名称
`timeoutMs`	`int`	`10000`	超时时间(毫秒)

返回值

类型	说明
`(bool, string)`	包含成功状态和消息

调用示例

csharp

private RobotSDKManager _robotSDKManager;
private RobotMutiMediaClient _robotMutiMediaClient;

_robotMutiMediaClient = _robotSDKManager.CreateRobotMutiMediaClient();

var result = _robotMutiMediaClient.CaptureImage("rgb", "photo1");

C++ 接口

`CaptureImageReply captureImage(const std::string &image_type = "rgb", const std::string &image_name = "")`

功能说明
拍摄照片。

参数说明

参数名	类型	必填/默认值	说明
`image_type`	`string`	`rgb`	图片类型
`image_name`	`string`	选填	图片名称

返回值

类型	说明
`CaptureImageReply`	包含成功标志、消息和文件路径

调用示例

cpp

Lenovo::Daystar::SDK sdk;
auto &sysb = sdk.getSYSB();

std::cout << "图像类型选择: 1=RGB, 2=红外(infra)" << std::endl;
int type_choice = getIntInput("选择图像类型(1或2，默认1): ");
std::string image_type = (type_choice == 2) ? "infra" : "rgb";
                
std::string image_name = getStringInput("输入图像文件名(不含扩展名，留空自动生成): ");
                
auto result = sysb.captureImage(image_type, image_name);
if (result.success)
{
    std::cout << "✓ 图像已拍摄 (类型: " << image_type << ")" << std::endl;
    if (!result.file_path.empty()) {
        std::cout << "  图像路径: " << result.file_path << std::endl;
    }
}
else
{
    std::cout << "✗ 拍照失败: " << result.message << std::endl;
}

Java 接口

`ServiceOperationResponse CapturePtzImage(String imageType, String savePath)`

功能说明
拍摄图像并保存到指定路径。

参数说明

参数名	类型	必填/默认值	说明
`imageType`	`String`	必填	图片类型 ("rgb" 或 "infra")
`savePath`	`String`	必填	保存路径

返回值

类型	说明
`ServiceOperationResponse`	操作结果

调用示例

java

client.CapturePtzImage("rgb", "my_image");

下载图片

Python 接口

`async def download_image(image_name: str) -> bytes`

功能说明
下载已拍摄的图片。

参数说明

参数名	类型	必填/默认值	说明
`image_name`	`str`	必填	图片名称（不含扩展名）

返回值

类型	说明
`bytes`	图片二进制数据

调用示例

python

data = await client.download_image("my_photo")

C# 接口

`void DownloadImage(string imageName, int requestId = 400, int timeoutMs = 30000)`

功能说明
异步下载图片。需先注册 FetchAssetResponseCallback 接收数据。

参数说明

参数名	类型	必填/默认值	说明
`imageName`	`string`	必填	图片名称
`requestId`	`int`	默认 400	请求ID（可忽略）

返回值

类型	说明
`void`	无返回值，通过回调接收数据

调用示例

csharp

private RobotSDKManager _robotSDKManager;
private RobotMutiMediaClient _robotMutiMediaClient;

_robotMutiMediaClient = _robotSDKManager.CreateRobotMutiMediaClient();

 Action<FetchAssetResponse> fetchHandler = null;
fetchHandler = (response) =>
{
    try
    {
        if (response == null || response.request_id != 400)
        {
            return;
        }

        // 取消注册（示例中使用单次回调）
        _robotMutiMediaClient.UnregisterFetchAssetResponseCallback();

        if (response.IsSuccess && response.data != null && response.data.Length > 0)
        {
            Debug.Log($"✓ PTZ image downloaded successfully: {response.data.Length} bytes");

            // 确保目标目录存在
            string directory = System.IO.Path.GetDirectoryName(saveToPath);
            if (!string.IsNullOrEmpty(directory) && !System.IO.Directory.Exists(directory))
            {
                System.IO.Directory.CreateDirectory(directory);
                Debug.Log($"Created directory: {directory}");
            }

            // 保存到本地文件
            System.IO.File.WriteAllBytes(saveToPath, response.data);
            Debug.Log($"✓ PTZ image saved to: {saveToPath}");
        }
        else
        {
            Debug.LogError($"✗ PTZ image download failed: {response?.error_message}");
        }
    }
    catch (System.Exception ex)
    {
        Debug.LogError($"Exception in fetch handler: {ex.Message}");
    }
};

_robotMutiMediaClient.RegisterFetchAssetResponseCallback((response) => {
    // 处理 response.data
});
_robotMutiMediaClient.DownloadImage("photo1", 123);

C++ 接口

`CommReply downloadImage(const std::string &image_name, std::vector<uint8_t> &file_data)`

功能说明
下载图片。

参数说明

参数名	类型	必填/默认值	说明
`image_name`	`string`	必填	图片名称
`file_data`	`vector<uint8_t>&`	输出	存储图片数据的缓冲区

返回值

类型	说明
`CommReply`	包含成功状态和消息

调用示例

cpp

Lenovo::Daystar::SDK sdk;
auto &sysb = sdk.getSYSB();
std::string image_name = getStringInput("输入图像名称: ");
std::vector<uint8_t> file_data;

auto result = sysb.downloadImage(image_name, file_data);
if (result.success == true)
{
    // 图片文件保存为.jpeg格式（如果还没有扩展名）
    std::string filename = image_name;
    if (filename.find(".") == std::string::npos) {
        filename += ".jpeg";
    }
                    
    std::string download_dir = ensureDownloadDir();
    std::string save_path = download_dir + "/" + filename;
                    
    std::ofstream out_file(save_path, std::ios::binary);
    if (!out_file) {
        std::cout << "✗ 无法创建文件: " << save_path << std::endl;
        break;
    }
                    
    out_file.write(reinterpret_cast<const char *>(file_data.data()), file_data.size());
    out_file.close();
                    
    if (out_file.fail()) {
        std::cout << "✗ 文件写入失败: " << save_path << std::endl;
    } else {
        std::cout << "✓ 图像文件下载成功" << std::endl;
        std::cout << "  文件大小: " << (file_data.size() / 1024.0) << " KB" << std::endl;
        std::cout << "  保存路径: " << save_path << std::endl;
    }
}
else
{
    std::cout << "✗ 图像文件下载失败: " << result.message << std::endl;
}

Java 接口

`CompletableFuture<byte[]> downloadImage(String imageName, int timeoutSeconds)`

功能说明
异步下载图片。

参数说明

参数名	类型	必填/默认值	说明
`imageName`	`String`	必填	图片名称
`timeoutSeconds`	`int`	必填	超时时间(秒)

返回值

类型	说明
`CompletableFuture<byte[]>`	包含图片数据的Future

调用示例

java

client.downloadImage("my_image", 30).thenAccept(data -> {
    // 处理数据
});

机器狗服务

通用任务服务接口

多媒体服务接口 ​

云台视频流服务 ​

硬件 ​

软件接口 ​

注意事项 ​

视频流验证与测试 ​

云台控制接口 ​

获取云台姿态信息 ​

ROS2 接口 ​

Python 接口 ​

subscribe_ptzf_position(ptzf_position_callback) ​

unsubscribe_ptzf_position() ​

C# 接口 ​

void SubscribePtzPosition(Action<PtzPositionStamped> callback = null) ​

void UnsubscribePtzPosition() ​

C++ 接口 ​

bool subscribePtzfPosition() ​

bool unsubscribePtzfPosition() ​

Java 接口 ​

void SubscribesysbfPosition(Consumer<Object> callback) ​

控制云台运动角度 ​

ROS2 接口 ​

Python 接口 ​

set_ptzf_position(position: PtzfPosition, relative) ​

C# 接口 ​

void SetPtzPosition(float pan, float tilt, float zoom, ushort focus, bool relative = false) ​

C++ 接口 ​

void callPTZPosition(float pan, float tilt, float zoom, uint16_t focus, bool relative = false) ​

Java 接口 ​

void SetsysbPosition(PtzPosition position) ​

控制云台持续运动 ​

ROS2 接口 ​

Python 接口 ​

publish_ptzf_cmd_vel(cmd_vel: PtzfCmdVel) ​

C# 接口 ​

void MovePtzContinues(float panSpeed, float tiltSpeed, float zoomSpeed, float focusSpeed = 0) ​

C++ 接口 ​

void publishPtzfCmdVel(float pan, float tilt, float zoom, float focus) ​

Java 接口 ​

void MovesysbContinues(PtzPosition position) ​

辅助聚焦 ​

ROS2 接口 ​

Python 接口 ​

auto_focus(focus_mode, pixel_bbox=None) ​

C#接口 ​

bool AutoFocus(int focusMode = 1, PixelBoundingBox? pixelBbox = null, int timeoutMs = 8000) ​

C++ 接口 ​

bool autoFocus(int focus_mode = 1) ​

Java 接口 ​

void AutoFocus(int focusMode, PixelBoundingBox boundingBox) ​

切换对焦模式 ​

ROS2 接口 ​

Python 接口 ​

set_focus_mode(focus_mode) ​

C#接口 ​

bool SetFocusMode(int focusMode, int timeoutMs = 8000) ​

C++ 接口 ​

bool setFocusMode(int focus_mode) ​

Java 接口 ​

void SetFocusMode(int focusMode) ​

灯光控制 ​

ROS2 接口 ​

Python 接口 ​

light_cmd(enable) ​

C#接口 ​

void SetPtzLight(bool enable) ​

Java 接口 ​

void LightCmd(boolean enable) ​

​

C++ 接口 ​

bool lightCmd(bool enable) ​

云台拍照 ​

Python 接口 ​

async def capture_image(image_type: str = "rgb", image_name: str = "") -> dict ​

C# 接口 ​

(bool success, string message) CaptureImage(string type, string imageName, int timeoutMs = 10000) ​

C++ 接口 ​

CaptureImageReply captureImage(const std::string &image_type = "rgb", const std::string &image_name = "") ​

多媒体服务接口

云台视频流服务

硬件

软件接口

注意事项

视频流验证与测试

云台控制接口

获取云台姿态信息

ROS2 接口

Python 接口

`subscribe_ptzf_position(ptzf_position_callback)`

`unsubscribe_ptzf_position()`

C# 接口

`void SubscribePtzPosition(Action<PtzPositionStamped> callback = null)`

`void UnsubscribePtzPosition()`

C++ 接口

`bool subscribePtzfPosition()`

`bool unsubscribePtzfPosition()`

Java 接口

`void SubscribesysbfPosition(Consumer<Object> callback)`

控制云台运动角度

ROS2 接口

Python 接口

`set_ptzf_position(position: PtzfPosition, relative)`

C# 接口

`void SetPtzPosition(float pan, float tilt, float zoom, ushort focus, bool relative = false)`

C++ 接口

`void callPTZPosition(float pan, float tilt, float zoom, uint16_t focus, bool relative = false)`

Java 接口

`void SetsysbPosition(PtzPosition position)`

控制云台持续运动

ROS2 接口

Python 接口

`publish_ptzf_cmd_vel(cmd_vel: PtzfCmdVel)`

C# 接口

`void MovePtzContinues(float panSpeed, float tiltSpeed, float zoomSpeed, float focusSpeed = 0)`

C++ 接口

`void publishPtzfCmdVel(float pan, float tilt, float zoom, float focus)`

Java 接口

`void MovesysbContinues(PtzPosition position)`

辅助聚焦

ROS2 接口

Python 接口

`auto_focus(focus_mode, pixel_bbox=None)`

C#接口

`bool AutoFocus(int focusMode = 1, PixelBoundingBox? pixelBbox = null, int timeoutMs = 8000)`

C++ 接口

`bool autoFocus(int focus_mode = 1)`

Java 接口

`void AutoFocus(int focusMode, PixelBoundingBox boundingBox)`

切换对焦模式

ROS2 接口

Python 接口

`set_focus_mode(focus_mode)`

C#接口

`bool SetFocusMode(int focusMode, int timeoutMs = 8000)`

C++ 接口

`bool setFocusMode(int focus_mode)`

Java 接口

`void SetFocusMode(int focusMode)`

灯光控制

ROS2 接口

Python 接口

`light_cmd(enable)`

C#接口

`void SetPtzLight(bool enable)`

Java 接口

`void LightCmd(boolean enable)`

C++ 接口

`bool lightCmd(bool enable)`

云台拍照

Python 接口

`async def capture_image(image_type: str = "rgb", image_name: str = "") -> dict`

C# 接口

`(bool success, string message) CaptureImage(string type, string imageName, int timeoutMs = 10000)`

C++ 接口

`CaptureImageReply captureImage(const std::string &image_type = "rgb", const std::string &image_name = "")`

Java 接口

`ServiceOperationResponse CapturePtzImage(String imageType, String savePath)`

下载图片