Skip to content

Classes

DroneEnv(render_mode=None, video='', render_fps=30, terminated_step=3600, fixed=False, rel_alt_value=None, show_fps_flag=False, hover_z=True, hover_xy=True, perspective=True)

A simulated environment for validating vision-based drone navigation.

This class provides a Gymnasium-like environment for a drone navigating in a simulated world. It handles rendering, physics, and state management.

Parameters:

Name Type Description Default
render_mode Optional[str]

The rendering mode ('human' or 'rgb_array').

 None
video str

The path to the background video.

 ''
render_fps int

The frames per second for rendering.

 30
terminated_step int

The step at which the environment is considered terminated (at 30 FPS 3600 are 2 minutes).

 3600
fixed bool

Whether the background is a fixed image or a video.

 False
rel_alt_value Optional[float]

Initial relative altitude of the drone in meters. If not provided, it will be extracted from the video metadata or SRT file.

 None
show_fps_flag bool

Whether to display the FPS on terminal.

 False
hover_z bool

Whether to enable automatic altitude control (Z axis).

 True
hover_xy bool

Whether to enable automatic position control (X and Y axes).

 True
perspective bool

Whether to enable the perspective transformation. If False, only yaw rotation is used.

 True

render()

Renders the environment.

Returns:

Type Description
Optional[ndarray]

Optional[np.ndarray]: The rendered frame, if render_mode is 'rgb_array'.
Example

You can see an example of the rendering method on usage documentation.

reset(x=None, y=None, z=None, psi_deg_init=None)

Resets the environment to an initial state.

Parameters:

Name Type Description Default
x Optional[float]

Initial x position of the drone in meters. If None, a random value is chosen.

 None
y Optional[float]

Initial y position of the drone in meters. If None, a random value is chosen.

 None
z Optional[float]

Initial z position of the drone in meters. If None, a random value is chosen between 20 and (min(60, self.height - 1)).

 None
psi_deg_init Optional[float]

Initial yaw in degrees. If None, a random value is chosen between 0 and 360.

 None

Returns:

Name Type Description
observation ndarray

The current drone camera view (RGB image).
info Dict[str, Any]

A dictionary containing auxiliary information, such as 'points' (coordinates for rendering), 'drone_state' (position and velocity), and 'actions' (the actions taken).

set_state(x, y, z, roll, pitch, yaw, fk=0.0)

Sets the drone state directly and updates the view.

Parameters:

Name Type Description Default
x float

X position in meters.

 required
y float

Y position in meters.

 required
z float

Z position in meters.

 required
roll float

Roll angle in degrees.

 required
pitch float

Pitch angle in degrees.

 required
yaw float

Yaw angle in degrees.

 required

Returns:

Name Type Description
observation ndarray

The current drone camera view (RGB image).
terminated bool

Whether the episode has terminated.
info Dict[str, Any]

Auxiliary information.

step(actions)

Executes one time step in the environment.

Parameters:

Name Type Description Default
actions ndarray

The actions to take in the environment:

  • actions[0]: phi (roll) in degrees.
  • actions[1]: theta (pitch) in degrees.
  • actions[2]: psi velocity (yaw rate) in degrees per second.
  • actions[3]: fk (Thrust) in newtons.
 required

Returns:

Name Type Description
observation ndarray

The current drone camera view (RGB image).
terminated bool

Whether the episode has terminated. This occurs when:

  • The simulation reaches 3600 steps (at 30 FPS 3600 are 2 minutes).
  • The virtual drone moves outside the simulation boundaries.
info Dict[str, Any]

A dictionary containing auxiliary information:

  • 'points' (coordinates for rendering).
  • 'drone_state' (position and velocity).
  • 'actions' (the actions taken, including the current yaw angle).

HMI(dead_zone=0.1)

Human-Machine Interface for controlling drone environments.

This class handles both joystick controller and keyboard inputs to generate control actions for a simulation. It provides universal controller support with consistent mappings across different controller types.

Parameters:

Name Type Description Default
dead_zone float

The dead zone threshold for joystick analog inputs (0.0 to 1.0).

 0.1

__call__()

Processes input and returns the current control state.

This method makes the HMI instance callable and should be used in the main control loop. It processes all pending events and updates control variables.

Returns:

Type Description
Tuple[ndarray, str | None, bool]

A tuple containing:

  • actions (np.ndarray): Control values [theta, phi, psi_velocity, fk].
    • actions[0]: theta (pitch) in degrees.
    • actions[1]: phi (roll) in degrees.
    • actions[2]: psi_velocity (yaw rate) in degrees per second.
    • actions[3]: fk (Thrust) in newtons.
  • command (str | None): Command string ("takeoff", "land", "reset") or None.
  • exit_requested (bool): True if an exit was requested.

quit()

Cleans up and shuts down the HMI system.