CameraCtrlApi 接口文档¶

简介¶

简述：本文件提供无人机仿真环境中吊舱相机的控制接口，核心支持通过键盘手动操控吊舱相机的姿态，用于调整仿真视角与视觉采集视角。

在RflySim无人机仿真的视觉相关任务开发中，吊舱相机的姿态调整是任务调试、视角观测的常用操作。本模块属于RflySimSDK的视觉工具组件，主要适用于仿真过程中需要手动调整相机观测角度的场景，例如无人机巡检目标观测、视觉导航任务视角调试、环境场景勘察等场景。其中KeyCtrl类可以直接通过方向键配合功能键，快速控制吊舱相机的俯仰角与偏航角，帮助开发人员便捷获取目标观测视角，完成仿真任务的调试与观测工作。

快速开始¶

最简可用示例，复制后修改最少配置即可运行。

from RflySimSDK.vision.CameraCtrlApi import KeyCtrl

# 1. 初始化键盘控制相机类，使用默认参数即可创建
key_camera_ctrl = KeyCtrl()

# 2. 循环获取当前相机云台姿态，同时可使用键盘控制相机
if __name__ == "__main__":
    # 进入循环读取和打印状态
    while True:
        # 获取当前云台Yaw偏航角
        current_yaw = key_camera_ctrl.getYaw()
        # 获取当前云台Pitch俯仰角
        current_pitch = key_camera_ctrl.getPitch()
        # 获取当前云台Roll滚转角
        current_roll = key_camera_ctrl.getRoll()

        # 打印当前姿态信息
        print(f"当前云台姿态 | Yaw: {current_yaw:.2f}  Pitch: {current_pitch:.2f}  Roll: {current_roll:.2f}")

        # 控制刷新频率，可根据需求修改
        import time
        time.sleep(0.1)

"""
控制说明：
方向键上下: 控制Pitch角度/角速度
方向键左右: 控制Yaw角度/角速度
数字键1: 切换角度/角速度控制模式
数字键3: 切换焦距/视场角控制模式
数字键5: 相机回中，重置角度为初始状态
数字键7/9: 调整焦距/视场角
"""

环境与依赖¶

Python 环境：>= 3.8.10
依赖库：cv2、keyboard、math、typing
前置准备：调用此接口前，必须先启动CopterSim仿真引擎并搭建好包含摄像头的仿真环境。

核心接口说明¶

该模块 CameraCtrlApi.py 包含了配置变量、辅助函数及核心业务类。

全局常量与枚举定义¶

本节列出模块中所有可直接引用的全局常量和枚举定义。

独立常量¶

无

全局/独立函数¶

无

`ImageCtrl` 类¶

用于无人机仿真环境中对图像进行窗口设置、可视化标记绘制的工具类，可实现图像显示、辅助标记（十字、坐标系、姿态）绘制功能，常用于计算机视觉算法开发的可视化调试场景。

`init(screenWidth=640, screenHeight=480)`¶

功能说明：初始化 ImageCtrl 实例，设置默认图像分辨率 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`screenWidth`	`int`	否	`640`	图像默认宽度，单位像素
`screenHeight`	`int`	否	`480`	图像默认高度，单位像素

返回值 (Returns)：

ImageCtrl 实例对象

异常 (Raises)：无

`setRect(window_w, window_h)`¶

功能说明：设置显示窗口的尺寸，覆盖初始化时的默认分辨率 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`window_w`	`int`	是	-	目标窗口宽度，单位像素
`window_h`	`int`	是	-	目标窗口高度，单位像素

返回值 (Returns)：

无

异常 (Raises)：无

`DisplayImg(img)`¶

功能说明：在窗口中显示输入图像 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`img`	`np.ndarray`	是	-	待显示的OpenCV格式图像数组

返回值 (Returns)：

无

异常 (Raises)：无

示例：

import cv2
from RflySimSDK.vision import ImageCtrl

# 初始化图像控制器，设置640x480分辨率
img_ctrl = ImageCtrl(640, 480)
# 读取仿真相机图像
img = cv2.imread("drone_camera.jpg")
# 显示图像
img_ctrl.DisplayImg(img)
cv2.waitKey(1)

`drawCross()`¶

功能说明：在图像中心绘制十字标记，用于辅助对准中心点 参数列表 (Args)：无 返回值 (Returns)：

无

异常 (Raises)：无

`drawCrossRect()`¶

功能说明：在图像中心区域绘制带十字的矩形框，辅助标定中心区域范围 参数列表 (Args)：无 返回值 (Returns)：

无

异常 (Raises)：无

`drawPosture(roll, pitch, yaw)`¶

功能说明：在图像上绘制无人机姿态角信息标注 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`roll`	`float`	是	-	滚转角，单位度
`pitch`	`float`	是	-	俯仰角，单位度
`yaw`	`float`	是	-	偏航角，单位度

返回值 (Returns)：

无

异常 (Raises)：无

`drawCoordinate(CoordName, orientation, value, step=1, largeStep=4, minNum=0, maxNum=100, stepLength=2)`¶

功能说明：在图像边缘绘制带刻度的坐标轴，用于可视化数值参数大小 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`CoordName`	`str`	是	-	坐标轴名称，显示在坐标轴旁
`orientation`	`str`	是	-	坐标轴方位，可选水平/垂直
`value`	`float`	是	-	当前坐标轴标注值，会高亮显示当前位置
`step`	`int`	否	`1`	最小刻度间隔
`largeStep`	`int`	否	`4`	大刻度间隔，大刻度会标注数值
`minNum`	`float`	否	`0`	坐标轴最小值
`maxNum`	`float`	否	`100`	坐标轴最大值
`stepLength`	`int`	否	`2`	最小刻度线长度，单位像素

返回值 (Returns)：

无

异常 (Raises)：无

示例：

from RflySimSDK.vision import ImageCtrl

img_ctrl = ImageCtrl()
# 在图像左侧绘制垂直的高度坐标轴
img_ctrl.drawCoordinate(CoordName="Height(m)", orientation="vertical", value=25, minNum=0, maxNum=100)

`KeyCtrl` 类¶

该类是通过键盘控制吊舱相机运动，上(↑)下(↓)键控制俯仰角(pitch)；左(←)右(→)键控制偏航角(yaw)；右Ctrl键 + 左(←)右(→) 控制横滚角(roll)，焦距调节可通过alt+上、alt+下完成。

`init()`¶

功能说明：初始化键盘控制吊舱相机实例，支持自定义各功能激活状态、控制方式参数、相机参数等，可通过指定按键完成多种相机控制操作。 参数列表 (Args)：

参数名	类型	说明
`mask_***`	int	掩码参数，用于与功能做&比较，0表示对应功能未激活，1表示激活
`press_**`	-	自定义按键控制配置
`FOVOrFocalLength`	int	控制模式选择，0表示视场角模式，1表示焦距模式，模式切换时会自动同步焦距/视场角参数
`CameraFocalLength`	float	相机初始焦距
`CmaeraFocalLengthBaseNum`	float	焦距调节步长
`AngOrAngV`	int	控制模式选择，0表示角度模式，1表示角速度模式，切换至角度模式时会自动同步当前云台角度
`AngVel`	float	角速度控制模式下的默认角速度值
`CurOZ`	int	当前光学变倍倍数，默认为1
`OZBaseNum`	float	光学变倍基础步进基数
`TrackID`	int	需要追踪的目标ID

控制按键说明：上、下、左、右：Pitch、Yaw的角度/角速度控制 Num1：角度/角速度控制模式切换 Num3：焦距/视场角控制模式切换 Num5：相机回中，仅将云台角度恢复为初始化状态，不调整焦距 Num7、9：焦距/视场角手动控制 +、-：光学变倍，基于变倍基数调整，不基于当前焦距 /：开启默认目标ID追踪，默认目标ID为1000，仅供测试 *：切换相机传感器类型，0:可见光图像 1:热力图 2:红外灰度

返回值 (Returns)：无 异常 (Raises)：无

`getYaw()`¶

功能说明：获取相机当前偏航角（Yaw）角度值，单位为角度制 参数列表 (Args)：无参数 返回值 (Returns)：相机偏航角角度值 异常 (Raises)：无

`getPitch()`¶

功能说明：获取相机当前俯仰角（Pitch）角度值，单位为角度制 参数列表 (Args)：无参数 返回值 (Returns)：相机俯仰角角度值 异常 (Raises)：无

`getRoll()`¶

功能说明：获取相机当前滚转角（Roll）角度值，单位为角度制 参数列表 (Args)：无参数 返回值 (Returns)：相机滚转角角度值 异常 (Raises)：无

`getCameraFOV()`¶

功能说明：获取相机当前视场角（FOV） 参数列表 (Args)：无参数 返回值 (Returns)：相机视场角数值 异常 (Raises)：无

`getRadiansAngEular()`¶

功能说明：获取弧度制的相机欧拉角 参数列表 (Args)：无参数 返回值 (Returns)：弧度制的相机欧拉角数组，按 [俯仰角, 滚转角, 偏航角] 顺序排列 异常 (Raises)：无

`upPress()`¶

功能说明：处理相机向上按键按下事件，增加相机俯仰角，调整相机视角向上 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无

`downPress()`¶

功能说明：处理相机向下按键按下事件，减小相机俯仰角，调整相机视角向下 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无

`rightPress()`¶

功能说明：处理相机向右按键按下事件，增加相机偏航角，调整相机视角向右 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无

`leftPress()`¶

功能说明：处理相机向左按键按下事件，减小相机偏航角，调整相机视角向左 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无

`ctrlLeftPress()`¶

功能说明：处理Ctrl+左按键按下事件，减小相机滚转角，调整相机滚转姿态向左 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无

`ctrlRightPress()`¶

功能说明：处理Ctrl+右按键按下事件，增加相机滚转角，调整相机滚转姿态向右 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无

`altUpPress()`¶

功能说明：处理Alt+上按键按下事件，增大相机视场角（FOV），拉近拍摄视角 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无

`altDownPress()`¶

功能说明：处理Alt+下按键按下事件，减小相机视场角（FOV），拉远拍摄视角 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无

`Reset()`¶

功能说明：重置相机姿态角和视场角到初始默认状态 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无

`inner(angle, i)`¶

功能说明：限幅处理，将指定角度分量限制在合理范围内 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
angle	任意	是	无	原始欧拉角数组
i	任意	是	无	需要限幅的欧拉角分量索引

返回值 (Returns)：限幅处理后的对应角度分量值 异常 (Raises)：无

`fun(angle)`¶

功能说明：无额外功能说明 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
angle	None	是	无	待处理的角度值

返回值 (Returns)：将输入角度限制在(-π, π)范围内后的角度值 异常 (Raises)：无

`CheckAngleWid()`¶

功能说明：检查每个角度是否处于(-π, π)范围内 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无

`callback(key_v)`¶

功能说明：键盘按键事件回调函数，处理按键输入 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
key_v	None	是	无	触发回调的按键值

返回值 (Returns)：无 异常 (Raises)：无

`initkey()`¶

功能说明：初始化键盘控制相关配置 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无

进阶用法示例¶

展示复杂组合场景（如多类协作、异步控制、批量操作）

import RflySimSDK.vision as vis
import time
from concurrent.futures import ThreadPoolExecutor

# 多类协作示例：实现云台异步控制+实时检测结果可视化组合
img_ctrl = vis.ImageCtrl()
key_ctrl = vis.KeyCtrl()
target_list = [(100, 100), (200, 300), (350, 250)]  # 预定义的多个目标坐标

def async_vis_process(frame):
    """异步可视化任务：批量标注多个目标"""
    for x, y in target_list:
        img_ctrl.drawCross(frame, x, y)  # 批量绘制目标中心点
        img_ctrl.drawCrossRect(frame, x-20, y-20, x+20, y+20) # 绘制目标框
    # 绘制当前云台姿态坐标系
    current_eular = key_ctrl.getRadiansAngEular()
    img_ctrl.drawCoordinate(frame, 50, 50, current_eular)
    return img_ctrl.DisplayImg(frame)

# 异步控制云台追踪+实时可视化
with ThreadPoolExecutor() as executor:
    for _ in range(15):
        # 根据当前偏航角调整云台位置
        current_yaw = key_ctrl.getYaw()
        if current_yaw < -5:
            key_ctrl.leftPress()
        elif current_yaw > 5:
            key_ctrl.rightPress()
        # 异步提交可视化任务不阻塞云台控制
        latest_frame = get_latest_camera_frame()  # 从仿真环境获取最新相机帧
        executor.submit(async_vis_process, latest_frame)
        time.sleep(0.1)

在该复杂场景中，我们结合了KeyCtrl的云台姿态读取、按键控制能力，以及ImageCtrl的批量图形绘制能力，通过异步线程池实现了云台动态控制和多目标实时可视化的并行运行，适配多机协同视觉追踪场景的开发需求。

注意事项与避坑指南¶

角度单位差异: getYaw/getPitch/getRoll返回的是角度值，而getRadiansAngEular返回的是弧度制欧拉角，调用drawCoordinate绘制姿态坐标系时需确认输入参数的单位匹配，避免出现绘制姿态完全错误的问题。
图像操作输入要求: ImageCtrl所有绘图方法要求输入的图像帧为仿真环境输出的OpenCV格式numpy数组，传入自定义图像时需确保数组维度、数据类型匹配，否则会引发程序崩溃。
云台控制按键间隔: 调用upPress/leftPress等云台控制方法后，需要添加至少0.05秒的延时才能让仿真端完成姿态更新，连续无间隔调用会导致控制指令丢失，云台无法响应预期动作。
可视化资源释放: 每次仿真任务结束后需要确认关闭DisplayImg生成的显示窗口，未正确释放窗口资源会导致后台残留进程，占用过多系统内存。

更新日志¶

2024-08-05: fix：增加HTML版API注释
2024-07-18: fix:更新API主页索引
2024-07-17: fix：更新VisionCaptureApi接口API
2024-07-10: 融合吊舱程序所用接口内容
2023-11-09: fix: 增加自动化安全评估的接口类文件

CameraCtrlApi 接口文档¶

简介¶

快速开始¶

环境与依赖¶

核心接口说明¶

全局常量与枚举定义¶

独立常量¶

全局/独立函数¶

ImageCtrl 类¶

__init__(screenWidth=640, screenHeight=480)¶

setRect(window_w, window_h)¶

DisplayImg(img)¶

drawCross()¶

drawCrossRect()¶

drawPosture(roll, pitch, yaw)¶

drawCoordinate(CoordName, orientation, value, step=1, largeStep=4, minNum=0, maxNum=100, stepLength=2)¶

KeyCtrl 类¶

__init__()¶

getYaw()¶

getPitch()¶

getRoll()¶

getCameraFOV()¶

getRadiansAngEular()¶

upPress()¶

downPress()¶

rightPress()¶

leftPress()¶

ctrlLeftPress()¶

ctrlRightPress()¶

altUpPress()¶

altDownPress()¶

Reset()¶

inner(angle, i)¶

fun(angle)¶

CheckAngleWid()¶

callback(key_v)¶

initkey()¶

进阶用法示例¶

注意事项与避坑指南¶

更新日志¶

`ImageCtrl` 类¶

`init(screenWidth=640, screenHeight=480)`¶

`setRect(window_w, window_h)`¶

`DisplayImg(img)`¶

`drawCross()`¶

`drawCrossRect()`¶

`drawPosture(roll, pitch, yaw)`¶

`drawCoordinate(CoordName, orientation, value, step=1, largeStep=4, minNum=0, maxNum=100, stepLength=2)`¶

`KeyCtrl` 类¶

`init()`¶

`getYaw()`¶

`getPitch()`¶

`getRoll()`¶

`getCameraFOV()`¶

`getRadiansAngEular()`¶

`upPress()`¶

`downPress()`¶

`rightPress()`¶

`leftPress()`¶

`ctrlLeftPress()`¶

`ctrlRightPress()`¶

`altUpPress()`¶

`altDownPress()`¶

`Reset()`¶

`inner(angle, i)`¶

`fun(angle)`¶

`CheckAngleWid()`¶

`callback(key_v)`¶

`initkey()`¶