Control-mode mapping utilities for NumPy-based controller pipelines.
Classes:
| Name | Description |
|---|---|
FlightMappingConfig |
Mapping-range configuration for normalized action scaling. |
FlightMappingResult |
Mapped result for a normalized flight action or action batch. |
FlightActionMapper |
Map normalized actions into controller targets, wrench commands, or RPM. |
Functions:
| Name | Description |
|---|---|
target_to_command |
Convert a dict target into a compact command vector. |
Attributes:
| Name | Type | Description |
|---|---|---|
CONTROLLER_REGISTRY |
dict[str, type]
|
Registry mapping controller name strings to their classes. |
ACTION_KEY_ORDER |
Explicit ordering for mapping action tensor slices to dict keys. |
module-attribute
CONTROLLER_REGISTRY: dict[str, type] = {'FlightController': FlightController, 'GeoControl': GeoControl}
Registry mapping controller name strings to their classes.
Shared with ControlActionCfg.controller so that sim2sim / sim2real
runtimes use the same resolution logic as IsaacLab training tasks.
module-attribute
ACTION_KEY_ORDER = ('thrust', 'pos', 'vel', 'att_euler', 'att_quat', 'att_rotmat', 'att_rotvec', 'ang_vel')
Explicit ordering for mapping action tensor slices to dict keys.
Used by FlightActionMapper.map_action to ensure deterministic slice
assignment regardless of dict insertion order.
dataclass
FlightMappingConfig(velocity_range: tuple[float, float, float] | None = None, attitude_range: tuple[float, float, float] | None = None, body_rate_range: tuple[float, float, float] | None = (2.0, 2.0, 2.0), rel_rotation: bool = False, rotation_step_len: float | None = None)
Mapping-range configuration for normalized action scaling.
Relative rotation fields mirror step_len / control_mode from
so3_primer.rotations.envs.rot.RotEnv.__init__ and the benchmark
wrappers:
so3_primer.benchmarks.crazyflow.utils.utils.RotationCrazyflowWrapper,
so3_primer.benchmarks.droneracing.utils.utils.RotationDroneRacingWrapper,
and so3_primer.benchmarks.robosuite.utils.utils.RotationGymWrapper.
Methods:
| Name | Description |
|---|---|
from_params |
Build mapping ranges from vehicle parameters. |
resolve |
Resolve config overrides into concrete mapping ranges. |
Attributes:
| Name | Type | Description |
|---|---|---|
velocity_range |
tuple[float, float, float] | None
|
Velocity scaling in m/s for x, y, z axes. |
attitude_range |
tuple[float, float, float] | None
|
Attitude scaling in radians. |
body_rate_range |
tuple[float, float, float] | None
|
Body-rate scaling in rad/s. |
rel_rotation |
bool
|
Whether attitude actions are relative deltas rather than absolute targets. |
rotation_step_len |
float | None
|
Relative rotation scale. Primer defines max step as |
class-attribute
instance-attribute
velocity_range: tuple[float, float, float] | None = None
Velocity scaling in m/s for x, y, z axes.
class-attribute
instance-attribute
attitude_range: tuple[float, float, float] | None = None
Attitude scaling in radians.
class-attribute
instance-attribute
body_rate_range: tuple[float, float, float] | None = (2.0, 2.0, 2.0)
Body-rate scaling in rad/s.
class-attribute
instance-attribute
rel_rotation: bool = False
Whether attitude actions are relative deltas rather than absolute targets.
class-attribute
instance-attribute
rotation_step_len: float | None = None
Relative rotation scale. Primer defines max step as step_len * pi radians.
classmethod
from_params(params: VehicleParams) -> FlightMappingConfig
Build mapping ranges from vehicle parameters.
The returned ranges are chosen to broadly cover the controller range
exposed by VehicleParams without requiring exact one-to-one
alignment with the internal PX4-style controller limits.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
|
VehicleParams
|
Vehicle parameters providing the reference control bounds. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
FlightMappingConfig |
FlightMappingConfig
|
Mapping ranges derived from |
resolve(params: VehicleParams) -> FlightMappingConfig
Resolve config overrides into concrete mapping ranges.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
|
VehicleParams
|
Vehicle parameters providing fallback control bounds. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
FlightMappingConfig |
FlightMappingConfig
|
Concrete mapping ranges for runtime use. |
dataclass
FlightMappingResult(rpm_command: ndarray | Tensor, control: ndarray | Tensor | None = None, target: dict | None = None)
Mapped result for a normalized flight action or action batch.
FlightActionMapper(control_mode: str, params: VehicleParams = VehicleParams(), mapping: FlightMappingConfig | None = None, control_mask: dict | None = None)
Map normalized actions into controller targets, wrench commands, or RPM.
Initialize a NumPy flight action mapper for the selected control mode.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
|
str
|
Control mode string (e.g. |
required |
|
VehicleParams
|
Vehicle parameters for action scaling. |
VehicleParams()
|
|
FlightMappingConfig | None
|
Optional mapping-range overrides. Relative-rotation
behaviour is controlled via
:attr: |
None
|
|
dict | None
|
Per-key boolean mask dict. |
None
|
Methods:
| Name | Description |
|---|---|
action_to_collective_acc |
Map a normalized policy collective action to total collective acceleration. |
collective_acc_to_thrust |
Convert total collective acceleration into total thrust in Newtons. |
action_to_collective_thrust |
Convert a normalized policy collective action into total thrust. |
map_action |
Map a normalized action into an RPM command and optional intermediates. |
Attributes:
| Name | Type | Description |
|---|---|---|
requires_controller |
bool
|
Whether this mode needs a controller — true when mask has any keys. |
property
requires_controller: bool
Whether this mode needs a controller — true when mask has any keys.
action_to_collective_acc(action: float | ndarray, mixer: Mixer) -> np.ndarray
Map a normalized policy collective action to total collective acceleration.
collective_acc_to_thrust(collective_acc: float | ndarray) -> np.ndarray
Convert total collective acceleration into total thrust in Newtons.
action_to_collective_thrust(action: float | ndarray, mixer: Mixer) -> np.ndarray
Convert a normalized policy collective action into total thrust.
map_action(action: ndarray, mixer: Mixer, *, state: dict | None = None, flight_controller: ControllerBase | None = None) -> FlightMappingResult
Map a normalized action into an RPM command and optional intermediates.
target_to_command(target: dict, command_mode: str, state: dict | None = None, output_frame: str = 'world_relative') -> np.ndarray
Convert a dict target into a compact command vector.
target keys are pos(3), vel(3), att_euler(3), ang_vel(3), thrust(scalar).
The tgt_ctatt/tgt_ctbr modes read the dedicated thrust key instead
of overloading index 5.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
|
dict
|
Target state dict. |
required |
|
str
|
One of |
required |
|
dict | None
|
Current state dict; required for |
None
|
|
str
|
|
'world_relative'
|