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:

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; Right Ctrl + 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
`Cmaera

Function Description: Handles the event when the camera's right key is pressed, increasing the camera's yaw angle to pan the view to the right.
Parameters (Args): None
Return Value (Returns): None
Exceptions (Raises): None

`leftPress()`¶

Function Description: Handles the event when the camera's left key is pressed, decreasing the camera's yaw angle to pan the view to the left.
Parameters (Args): None
Return Value (Returns): None
Exceptions (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
Return Value (Returns): None
Exceptions (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
Return Value (Returns): None
Exceptions (Raises): None

`altUpPress()`¶

Function Description: Handles the event when Alt+Up is pressed, increasing the camera's field of view (FOV) to zoom in the viewing perspective.
Parameters (Args): None
Return Value (Returns): None
Exceptions (Raises): None

`altDownPress()`¶

Function Description: Handles the event when Alt+Down is pressed, decreasing the camera's field of view (FOV) to zoom out the viewing perspective.
Parameters (Args): None
Return Value (Returns): None
Exceptions (Raises): None

`Reset()`¶

Function Description: Resets the camera’s attitude angles and FOV to their initial default states.
Parameters (Args): None
Return Value (Returns): None
Exceptions (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

Return Value (Returns): The corresponding angular component value after clamping
Exceptions (Raises): None

`fun(angle)`¶

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

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

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

`CheckAngleWid()`¶

Function Description: Checks whether each angle lies within the range (-π, π).
Parameters (Args): None
Return Value (Returns): None
Exceptions (Raises): None

`callback(key_v)`¶

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

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

Return Value (Returns): None
Exceptions (Raises): None

`initkey()`¶

Function Description: Initializes keyboard control-related configuration.
Parameters (Args): None
Return Value (Returns): None
Exceptions (Raises): None

Advanced Usage Example¶

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

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

drawCross()¶

drawCrossRect()¶

drawPosture(roll, pitch, yaw)¶

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

KeyCtrl Class¶

__init__()¶

leftPress()¶

ctrlLeftPress()¶

ctrlRightPress()¶

altUpPress()¶

altDownPress()¶

Reset()¶

inner(angle, i)¶

fun(angle)¶

CheckAngleWid()¶

callback(key_v)¶

initkey()¶

Advanced Usage Example¶

Notes and Pitfall Avoidance Guide¶

Changelog¶

`ImageCtrl` Class¶

`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` Class¶

`init()`¶

`leftPress()`¶

`ctrlLeftPress()`¶

`ctrlRightPress()`¶

`altUpPress()`¶

`altDownPress()`¶

`Reset()`¶

`inner(angle, i)`¶

`fun(angle)`¶

`CheckAngleWid()`¶

`callback(key_v)`¶

`initkey()`¶