attitude

Attitude-aware MLP model with rotation-manifold projection for rsl-rl.

Mirrors lav2/runner/skrl/cfg/LAV2_base_att.py but adapted to rsl-rl's MLPModel interface so it can be referenced via class_name in a config dict.

Control modes and their action dimensions::

cmd_ctatt_euler → 4D [thrust, roll, pitch, yaw] cmd_ctatt_rotvec → 4D [thrust, rx, ry, rz] cmd_ctatt_quat → 5D [thrust, qx, qy, qz, qw] cmd_ctatt_rotmat → 10D [thrust, r00..r22]

Projection layers ensure the rotation component of the policy output lies on a valid manifold. The projection is applied between the MLP output and the distribution update for single-slice distributions (Gaussian), or to the first slice for multi-slice distributions (Beta, heteroscedastic Gaussian).

Classes:

Name	Description
`EulerProjection`	Bounded projection for euler-angle / rotation-vector actions.
`QuatProjection`	L2-normalize the 4-D quaternion at indices [1:5].
`QuatPlusProjection`	Quaternion projection with double-cover elimination.
`QuatOffsetProjection`	Quaternion projection centred at the identity rotation.
`QuatPlusOffsetProjection`	Quaternion projection combining offset and double-cover elimination.
`RotmatProjection`	SVD-orthogonalize the 9-D rotation-matrix at indices [1:10].
`RotmatOffsetProjection`	Rotation-matrix projection centred at the identity matrix.
`AttitudeMLPModel`	MLP model with optional rotation-manifold projection.

EulerProjection

Bases: Module

Bounded projection for euler-angle / rotation-vector actions.

Applies tanh to clamp all components to [-1, 1] so that the environment action scaling stays within the expected range.

Methods:

Name	Description
`forward`	Clamp x to `[-1, 1]` via tanh.

forward

forward(x: Tensor) -> torch.Tensor

Clamp x to [-1, 1] via tanh.

QuatProjection

Bases: Module

L2-normalize the 4-D quaternion at indices [1:5].

Applies tanh to bound all components, then normalizes the quaternion slice to unit length. The thrust channel (index 0) is passed through unchanged.

The double-cover ambiguity (q and -q) is left for the policy to resolve.

Methods:

Name	Description
`forward`	Normalize quaternion slice of x.

forward

forward(x: Tensor) -> torch.Tensor

Normalize quaternion slice of x.

QuatPlusProjection

Bases: Module

Quaternion projection with double-cover elimination.

The scalar component w is mapped through a sigmoid channel (tanh → [0, 1]) so that the output quaternion always satisfies w ≥ 0, breaking the q ≡ -q ambiguity.

Methods:

Name	Description
`forward`	Match the primer quadrotor quat-plus head.

forward

forward(x: Tensor) -> torch.Tensor

Match the primer quadrotor quat-plus head.

QuatOffsetProjection

QuatOffsetProjection()

Bases: Module

Quaternion projection centred at the identity rotation.

Adds the identity quaternion [0, 0, 0, 1] to the policy output, clamps to [-1, 1], then L2-normalizes. A zero policy output therefore commands hover attitude.

Register the identity-quaternion offset buffer.

Methods:

Name	Description
`forward`	Offset x by identity quaternion, then normalize.

forward

forward(x: Tensor) -> torch.Tensor

Offset x by identity quaternion, then normalize.

QuatPlusOffsetProjection

QuatPlusOffsetProjection()

Bases: Module

Quaternion projection combining offset and double-cover elimination.

Offsets the vector part by zero, maps w through a sigmoid channel, then L2-normalizes.

Register the zero-offset buffer for the vector part.

Methods:

Name	Description
`forward`	Offset vector part by zero, force `w ≥ 0`, then normalize.

forward

forward(x: Tensor) -> torch.Tensor

Offset vector part by zero, force w ≥ 0, then normalize.

RotmatProjection

Bases: Module

SVD-orthogonalize the 9-D rotation-matrix at indices [1:10].

Reshapes the matrix slice to (..., 3, 3), applies tanh to bound elements, then computes the least-squares orthogonal Procrustes projection via SVD. A determinant correction ensures the result lies in SO(3) (det=+1). The thrust channel (index 0) is passed through unchanged.

Methods:

Name	Description
`forward`	SVD-project the matrix slice of x onto SO(3).

forward

forward(x: Tensor) -> torch.Tensor

SVD-project the matrix slice of x onto SO(3).

RotmatOffsetProjection

RotmatOffsetProjection()

Bases: Module

Rotation-matrix projection centred at the identity matrix.

Adds the flattened 3×3 identity to the policy output, clamps to [-1, 1], then SVD-projects onto SO(3). A zero policy output therefore commands hover attitude.

Register the identity-matrix offset buffer.

Methods:

Name	Description
`forward`	Offset x by identity matrix, then SVD-project.

forward

forward(x: Tensor) -> torch.Tensor

Offset x by identity matrix, then SVD-project.

AttitudeMLPModel

AttitudeMLPModel(obs, obs_groups, obs_set, output_dim, hidden_dims=(128, 128), activation='tanh', obs_normalization=False, distribution_cfg=None, projection_type: str | None = None)

Bases: MLPModel

MLP model with optional rotation-manifold projection.

The projection is applied between the MLP output and the distribution update. This enforces rotation components to lie on valid manifolds (e.g. unit quaternion, orthogonal matrix).

Parameters:

Name	Type	Description	Default
`projection_type`	`str \| None`	Explicit projection name (one of `"euler"`, `"rotvec"`, `"quat"`, `"quat_plus"`, `"quat_offset"`, `"quat_plus_offset"`, `"rotmat"`, `"rotmat_offset"`). When `None`, auto-detected from `output_dim`.	`None`

Construct the model and append the projection to the MLP trunk.