CameraCtrlApi Interface Documentation¶

Introduction¶

Overview: This document provides the control interface for gimballed cameras in the drone simulation environment, primarily supporting manual keyboard-based control of the gimbal camera's attitude for adjusting simulation and visual acquisition perspectives.

In RflySim drone simulation development involving visual tasks, adjusting the gimbal camera's attitude is a common operation for task debugging and perspective observation. This module belongs to the visual tools component of RflySimSDK and is mainly applicable to scenarios requiring manual adjustment of the camera's viewing angle during simulation, such as drone inspection target observation, visual navigation task perspective debugging, and environmental scene reconnaissance. The KeyCtrl class enables rapid control of the gimbal camera’s pitch and yaw angles via directional keys combined with function keys, helping developers conveniently obtain target observation perspectives and complete simulation task debugging and observation.

Quick Start¶

Minimal runnable example; copy and modify minimal configuration to run.

from RflySimSDK.vision.CameraCtrlApi import KeyCtrl

# 1. Initialize the keyboard-controlled camera class; default parameters suffice for creation
key_camera_ctrl = KeyCtrl()

# 2. Continuously retrieve current gimbal attitude while enabling keyboard control
if __name__ == "__main__":
    # Enter loop to read and print status
    while True:
        # Get current gimbal Yaw angle
        current_yaw = key_camera_ctrl.getYaw()
        # Get current gimbal Pitch angle
        current_pitch = key_camera_ctrl.getPitch()
        # Get current gimbal Roll angle
        current_roll = key_camera_ctrl.getRoll()

        # Print current attitude information
        print(f"Current gimbal attitude | Yaw: {current_yaw:.2f}  Pitch: {current_pitch:.2f}  Roll: {current_roll:.2f}")

        # Control refresh rate; adjust as needed
        import time
        time.sleep(0.1)

"""
Control Instructions:
Up/Down Arrow Keys: Control Pitch angle / angular velocity
Left/Right Arrow Keys: Control Yaw angle / angular velocity
Digit Key 1: Toggle between angle / angular velocity control mode
Digit Key 3: Toggle between focal length / field-of-view control mode
Digit Key 5: Reset camera to center position, resetting angles to initial state
Digit Keys 7/9: Adjust focal length / field-of-view
"""

Environment and Dependencies¶

Python Environment: >= 3.8.10
Dependencies: cv2, keyboard, math, typing
Prerequisites: Before invoking this interface, the CopterSim simulation engine must be started and a simulation environment with a camera must be set up.

Core Interface Description¶

The module CameraCtrlApi.py includes configuration variables, helper functions, and core business classes.

Global Constants and Enumerations¶

This section lists all globally accessible constants and enumerations defined in the module.

Standalone Constants¶

None

Global / Standalone Functions¶

None

`ImageCtrl` Class¶

A utility class for image window setup and visual annotation drawing in drone simulation environments. It supports image display and auxiliary annotation (crosshair, coordinate system, attitude) rendering, commonly used for visual debugging in computer vision algorithm development.

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

Function Description: Initializes an ImageCtrl instance and sets the default image resolution.
Parameters (Args):

Parameter Name	Type	Required	Default	Description
`screenWidth`	`int`	No	`640`	Default image width in pixels
`screenHeight`	`int`	No	`480`	Default image height in pixels

Return Value (Returns):

ImageCtrl instance object

Exceptions (Raises): - None

`setRect(window_w, window_h)`¶

Function Description: Sets the display window size, overriding the default resolution set during initialization.
Parameters (Args):

Parameter Name	Type	Required	Default	Description
`window_w`	`int`	Yes	-	Target window width in pixels
`window_h`	`int`	Yes	-	Target window height in pixels

Return Value (Returns):

None

Exceptions (Raises): - None

`DisplayImg(img)`¶

Function Description: Displays the input image in the window.
Parameters (Args):

Parameter Name	Type	Required	Default	Description
`img`	`np.ndarray`	Yes	-	OpenCV-format image array to be displayed

Return Value (Returns):

None

Exceptions (Raises): - None

Example:

import cv2
from RflySimSDK.vision import ImageCtrl

# Initialize image controller with 640x480 resolution
img_ctrl = ImageCtrl(640, 480)
# Read simulated camera image
img = cv2.imread("drone_camera.jpg")
# Display image
img_ctrl.DisplayImg(img)
cv2.waitKey(1)

---

#### `drawCross()`

**Function Description**: Draws a cross marker at the image center to assist alignment with the center point.  
**Arguments (Args)**:  
None  

**Returns**:  
- None  

**Raises**:  
- None  

---

#### `drawCrossRect()`

**Function Description**: Draws a rectangular frame with a cross at the image center region to assist calibration of the central area range.  
**Arguments (Args)**:  
None  

**Returns**:  
- None  

**Raises**:  
- None  

---

#### `drawPosture(roll, pitch, yaw)`

**Function Description**: Draws annotations of drone attitude angles on the image.  
**Arguments (Args)**:

| Parameter Name | Type | Required | Default | Description |
| :--- | :--- | :---: | :--- | :--- |
| `roll` | `float` | Yes | - | Roll angle, in degrees |
| `pitch` | `float` | Yes | - | Pitch angle, in degrees |
| `yaw` | `float` | Yes | - | Yaw angle, in degrees |

**Returns**:  
- None  

**Raises**:  
- None  

---

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

**Function Description**: Draws a scaled coordinate axis along the image edge to visualize the magnitude of numerical parameters.  
**Arguments (Args)**:

| Parameter Name | Type | Required | Default | Description |
| :--- | :--- | :---: | :--- | :--- |
| `CoordName` | `str` | Yes | - | Name of the coordinate axis, displayed beside the axis |
| `orientation` | `str` | Yes | - | Axis orientation; options: `"horizontal"` or `"vertical"` |
| `value` | `float` | Yes | - | Current value to annotate on the axis; the corresponding position will be highlighted |
| `step` | `int` | No | `1` | Interval between minor ticks |
| `largeStep` | `int` | No | `4` | Interval between major ticks; major ticks are labeled with values |
| `minNum` | `float` | No | `0` | Minimum value of the coordinate axis |
| `maxNum` | `float` | No | `100` | Maximum value of the coordinate axis |
| `stepLength` | `int` | No | `2` | Length of minor tick marks, in pixels |

**Returns**:  
- None  

**Raises**:  
- None  

**Example**:

```python
from RflySimSDK.vision import ImageCtrl

img_ctrl = ImageCtrl()
# Draw a vertical height coordinate axis on the left side of the image
img_ctrl.drawCoordinate(CoordName="Height(m)", orientation="vertical", value=25, minNum=0, maxNum=100)

`KeyCtrl` Class¶

This class enables keyboard control of the gimbal camera's motion: the Up (↑) and Down (↓) keys control pitch; the Left (←) and Right (→) keys control yaw; the Right Ctrl key combined with Left (←) or Right (→) controls roll;焦距调节 (focal length adjustment) can be performed using Alt+Up or Alt+Down.

`init()`¶

Function Description: Initializes a keyboard-controlled gimbal camera instance, supporting customizable activation states for various functions, control parameter configurations, and camera parameters. Multiple camera control operations can be triggered via designated key presses.

Parameters (Args):

Parameter Name	Type	Description
`mask_***`	int	Mask parameter used for bitwise AND (`&`) comparison with functions; 0 indicates the corresponding function is inactive, 1 indicates active
`press_**`	-	Custom key control configuration
`FOVOrFocalLength`	int	Control mode selection: 0 for Field of View (FOV) mode, 1 for focal length mode; switching modes automatically synchronizes focal length/FOV parameters
`CameraFocalLength`	float	Initial camera focal length
`CmaeraFocalLengthBaseNum`	float	Step size for focal length adjustment
`AngOrAngV`	int	Control mode selection: 0 for angle mode, 1 for angular velocity mode; switching to angle mode automatically synchronizes the current gimbal angles
`AngVel`	float	Default angular velocity value in angular velocity control mode
`CurOZ`	int	Current optical zoom factor; default is 1
`OZBaseNum`	float	Base step size for optical zoom adjustment
`TrackID`	int	Target ID to be tracked

Key Control Instructions: - Up, Down, Left, Right: Angle or angular velocity control for pitch and yaw - Num1: Toggle between angle and angular velocity control modes - Num3: Toggle between focal length and FOV control modes - Num5: Reset camera to center position—restores only the gimbal angles to their initial state, without adjusting focal length - Num7, Num9: Manual focal length/FOV control - +, -: Optical zoom adjustment, based on zoom step size (not current focal length) - /: Enable default target ID tracking; default target ID is 1000 (for testing only) - *: Toggle camera sensor type: 0: visible light image, 1: thermal image, 2: infrared grayscale

Returns: None
Raises: None

`getYaw()`¶

Function Description: Retrieves the current yaw angle of the camera, in degrees
Parameters (Args): None
Returns: Camera yaw angle (in degrees)
Raises: None

`getPitch()`¶

Function Description: Retrieves the current pitch angle of the camera, in degrees
Parameters (Args): None
Returns: Camera pitch angle (in degrees)
Raises: None

`getRoll()`¶

Function Description: Retrieves the current roll angle of the camera, in degrees
Parameters (Args): None
Returns: Camera roll angle (in degrees)
Raises: None

`getCameraFOV()`¶

Function Description: Retrieves the current field of view (FOV) of the camera
Parameters (Args): None
Returns: Camera FOV value
Raises: None

`getRadiansAngEular()`¶

Function Description: Retrieves the camera’s Euler angles in radians
Parameters (Args): None
Returns: Array of camera Euler angles in radians, ordered as [pitch, roll, yaw]
Raises: None

`upPress()`¶

Function Description: Handles the event when the Up key is pressed, increasing the camera’s pitch angle to tilt the view upward
Parameters (Args): None
Returns: None
Raises: None

`downPress()`¶

Function Description: Handles the event when the Down key is pressed, decreasing the camera’s pitch angle to tilt the view downward
Parameters (Args): None
Returns: None
Raises: None

`rightPress()`¶

Function Description: Handles the event when the Right key is pressed, increasing the camera’s yaw angle to pan the view to the right
Parameters (Args): None
Returns: None
Raises: None

`leftPress()`¶

Function Description: Handles the event when the Left key is pressed, decreasing the camera’s yaw angle to pan the view to the left
Parameters (Args): None
Returns: None
Raises: None

`ctrlLeftPress()`¶

Function Description: Handles the event when Ctrl+Left is pressed, decreasing the camera’s roll angle to roll the camera leftward
Parameters (Args): None
Returns: None
Raises: None

`ctrlRightPress()`¶

Function Description: Handles the event when Ctrl+Right is pressed, increasing the camera’s roll angle to roll the camera rightward
Parameters (Args): None
Returns: None
Raises: None

`altUpPress()`¶

Function Description: Handles the event when Alt+Up is pressed, increasing the camera’s FOV to zoom in the viewing perspective
Parameters (Args): None
Returns: None
Raises: None

`altDownPress()`¶

Function Description: Handles the event when Alt+Down is pressed, decreasing the camera’s FOV to zoom out the viewing perspective
Parameters (Args): None
Returns: None
Raises: None

`Reset()`¶

Function Description: Resets the camera’s attitude angles and FOV to their initial default states
Parameters (Args): None
Returns: None
Raises: None

`inner(angle, i)`¶

Function Description: Clamps a specified Euler angle component within a valid range
Parameters (Args):

Parameter Name	Type	Required	Default	Description
angle	Any	Yes	None	Original Euler angle array
i	Any	Yes	None	Index of the Euler angle component to be clamped

Returns: The corresponding angular component value after clamping
Raises: None

`fun(angle)`¶

Function Description: No additional function description
Arguments (Args):

Argument Name	Type	Required	Default	Description
angle	None	Yes	None	The angular value to be processed

Returns: The angular value after clamping the input angle to the range (-π, π)
Raises: None

`CheckAngleWid()`¶

Function Description: Checks whether each angle lies within the range (-π, π)
Arguments (Args): No arguments
Returns: None
Raises: None

`callback(key_v)`¶

Function Description: Keyboard key press event callback function, handles key input
Arguments (Args):

Argument Name	Type	Required	Default	Description
key_v	None	Yes	None	The key value triggering the callback

Returns: None
Raises: None

`initkey()`¶

Function Description: Initializes keyboard control-related configuration
Arguments (Args): No arguments
Returns: None
Raises: None

Advanced Usage Example¶

Demonstrates complex composite scenarios (e.g., multi-class collaboration, asynchronous control, batch operations)

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

Multi-class collaboration example: combining asynchronous pan-tilt control with real-time detection result visualization¶

img_ctrl = vis.ImageCtrl() key_ctrl = vis.KeyCtrl() target_list = [(100, 100), (200, 300), (350, 250)] # Predefined multiple target coordinates

def async_vis_process(frame): """Asynchronous visualization task: batch-annotate multiple targets""" for x, y in target_list: img_ctrl.drawCross(frame, x, y) # Batch draw target center points img_ctrl.drawCrossRect(frame, x-20, y-20, x+20, y+20) # Draw target bounding boxes # Draw the current pan-tilt attitude coordinate system current_eular = key_ctrl.getRadiansAngEular() img_ctrl.drawCoordinate(frame, 50, 50, current_eular) return img_ctrl.DisplayImg(frame)

Asynchronous pan-tilt tracking control + real-time visualization¶

with ThreadPoolExecutor() as executor: for _ in range(15): # Adjust pan-tilt position based on current yaw angle current_yaw = key_ctrl.getYaw() if current_yaw < -5: key_ctrl.leftPress() elif current_yaw > 5: key_ctrl.rightPress() # Asynchronously submit visualization task without blocking pan-tilt control latest_frame = get_latest_camera_frame() # Retrieve the latest camera frame from the simulation environment executor.submit(async_vis_process, latest_frame) time.sleep(0.1)

In this complex scenario, we integrate the KeyCtrl's gimbal attitude reading and key control capabilities with the ImageCtrl's batch graphic drawing capability, achieving parallel execution of dynamic gimbal control and multi-target real-time visualization through an asynchronous thread pool, thereby meeting the development requirements for multi-machine collaborative visual tracking scenarios.

Notes and Pitfall Avoidance Guide¶

Angle Unit Discrepancy: getYaw/getPitch/getRoll return values in degrees, whereas getRadiansAngEular returns Euler angles in radians. When calling drawCoordinate to render the attitude coordinate system, ensure the input parameter units match to avoid completely erroneous attitude rendering.
Image Input Requirements for Image Operations: All drawing methods in ImageCtrl require input image frames to be OpenCV-format numpy arrays output by the simulation environment. When passing custom images, ensure the array dimensions and data types match; otherwise, program crashes may occur.
Gimbal Control Key Interval: After invoking gimbal control methods such as upPress/leftPress, a delay of at least 0.05 seconds is required for the simulation side to complete attitude updates. Consecutive calls without intervals will cause control commands to be lost, resulting in the gimbal failing to execute the expected actions.
Visualization Resource Release: After each simulation task concludes, ensure the display window generated by DisplayImg is properly closed. Failure to correctly release window resources will leave residual background processes, consuming excessive system memory.

Changelog¶

2024-08-05: fix: Added HTML version of API documentation
2024-07-18: fix: Updated API homepage index
2024-07-17: fix: Updated VisionCaptureApi interface
2024-07-10: Integrated interface contents used by the pod program
2023-11-09: fix: Added interface class file for automated security assessment

CameraCtrlApi Interface Documentation¶

Introduction¶

Quick Start¶

Environment and Dependencies¶

Core Interface Description¶

Global Constants and Enumerations¶

Standalone Constants¶

Global / Standalone Functions¶

ImageCtrl Class¶

__init__(screenWidth=640, screenHeight=480)¶

setRect(window_w, window_h)¶

DisplayImg(img)¶

KeyCtrl Class¶

__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()¶

Advanced Usage Example¶

Multi-class collaboration example: combining asynchronous pan-tilt control with real-time detection result visualization¶

Asynchronous pan-tilt tracking control + real-time visualization¶

Notes and Pitfall Avoidance Guide¶

Changelog¶

`ImageCtrl` Class¶

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

`setRect(window_w, window_h)`¶

`DisplayImg(img)`¶

`KeyCtrl` Class¶

`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()`¶