CameraCtrlApi 接口文档¶

简介¶

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

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

快速开始¶

以下示例使用键盘控制相机姿态和视场角，并在收到的图像上叠加十字线、边框、视场角及姿态信息。

参考例程：[RflySim安装路径]\RflySimAPIs\8.RflySimVision\2.AdvExps\e2_CameraKeyDemoOnWindows

import math

import CameraCtrlApi
import cv2
import VisionCaptureApi


vis = VisionCaptureApi.VisionCaptureApi()
keyCtrl = CameraCtrlApi.KeyCtrl()
imageCtrl = CameraCtrlApi.ImageCtrl()

vis.jsonLoad(1)
vis.startImgCap()

while True:
    sensorAngles = keyCtrl.AngEular
    for index in range(len(vis.hasData)):
        if not vis.hasData[index]:
            continue

        imageCtrl.DisplayImg(vis.Img[index])
        imageCtrl.setRect(
            vis.VisSensor[index].DataWidth,
            vis.VisSensor[index].DataHeight,
        )
        imageCtrl.drawCross()
        imageCtrl.drawCrossRect()
        imageCtrl.drawCoordinate(
            "FOV(deg):",
            "top",
            math.ceil(keyCtrl.getCameraFOV()),
            15,
            3,
            0,
            180,
            10,
        )
        imageCtrl.drawPosture(
            sensorAngles[0],
            sensorAngles[1],
            sensorAngles[2],
        )
        cv2.imshow("Img" + str(index), vis.Img[index])
        cv2.waitKey(1)

环境与依赖¶

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)：无

进阶用法示例¶

以下示例将键盘控制器读取到的偏航、横滚、俯仰和视场角状态发布到四个 ROS 话题，供其他 ROS 节点订阅。

参考例程：[RflySim安装路径]\RflySimAPIs\8.RflySimVision\2.AdvExps\e3_CamerKeyROSDemo\KeyCtrlNode

import CameraCtrlApi
import rospy
from std_msgs.msg import Float32
import time


keyCtrl = CameraCtrlApi.KeyCtrl()

rospy.init_node("key_ctrl_node", anonymous=True)
yawPublisher = rospy.Publisher("/set_yaw", Float32, queue_size=10)
rollPublisher = rospy.Publisher("/set_roll", Float32, queue_size=10)
pitchPublisher = rospy.Publisher("/set_pitch", Float32, queue_size=10)
fovPublisher = rospy.Publisher("/set_FOV", Float32, queue_size=10)

keyCtrl.AngEular = [0, 0, 0]
keyCtrl.CameraFOV = 90

while True:
    yawPublisher.publish(keyCtrl.getYaw())
    rollPublisher.publish(keyCtrl.getRoll())
    pitchPublisher.publish(keyCtrl.getPitch())
    fovPublisher.publish(keyCtrl.getCameraFOV())
    time.sleep(0.01)

注意事项与避坑指南¶

角度单位差异: 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()`¶