> ## Documentation Index
> Fetch the complete documentation index at: https://docs.generalrobotics.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Orientation

## Orientation

Inherits from: `object`

A class to represent the orientation as a quaternion

Attributes:
x (float): x component of quaternion
y (float): y component of quaternion
z (float): z component of quaternion
w (float): w component of quaternion (scalar)

Can be initialized with either quaternion components or Euler angles

### **init**

```python theme={null}
Orientation.__init__(x: float, y: float, z: float, w: float)
```

Initialize an Orientation with quaternion components.

<ResponseField name="Arguments">
  <ParamField query="x (float)" type="float" required>
    x component of quaternion
  </ParamField>

  <ParamField query="y (float)" type="float" required>
    y component of quaternion
  </ParamField>

  <ParamField query="z (float)" type="float" required>
    z component of quaternion
  </ParamField>

  <ParamField query="w (float)" type="float" required>
    w component of quaternion (scalar)
  </ParamField>
</ResponseField>

### **init**

```python theme={null}
Orientation.__init__(roll: float, pitch: float, yaw: float)
```

Initialize an Orientation with Euler angles.

<ResponseField name="Arguments">
  <ParamField query="roll (float)" type="float" required>
    Rotation around x-axis in radians
  </ParamField>

  <ParamField query="pitch (float)" type="float" required>
    Rotation around y-axis in radians
  </ParamField>

  <ParamField query="yaw (float)" type="float" required>
    Rotation around z-axis in radians
  </ParamField>
</ResponseField>

### **init**

```python theme={null}
Orientation.__init__(rotation_matrix: Union[np.ndarray, list])
```

Initialize an Orientation with a rotation matrix.

<ResponseField name="Arguments">
  <ParamField query="rotation_matrix (Union[np.ndarray, list])" type="Union[np.ndarray, list]" required>
    3x3 rotation matrix or 9/16-element list
  </ParamField>
</ResponseField>

### **init**

```python theme={null}
Orientation.__init__(quaternion: Union[list, np.ndarray])
```

Initialize an Orientation with a quaternion array.

<ResponseField name="Arguments">
  <ParamField query="quaternion (Union[list, np.ndarray])" type="Union[list, np.ndarray]" required>
    4-element array \[x, y, z, w]
  </ParamField>
</ResponseField>

### **init**

```python theme={null}
Orientation.__init__(x: Union[float, int, np.ndarray, list], y: Union[float, int] = None, z: Union[float, int] = None, w: Optional[Union[float, int]] = None)
```

Initialize an Orientation object.

This constructor supports multiple initialization methods:

1. Using quaternion components (x, y, z, w)
2. Using Euler angles (roll, pitch, yaw) where the first three arguments
   are interpreted as roll, pitch, and yaw respectively
3. Using a rotation matrix (3x3 numpy array or list)
4. Using a quaternion array (4-element list or numpy array)

<ResponseField name="Arguments">
  <ParamField query="x (Union[float, int, np.ndarray, list])" type="Union[float, int, np.ndarray, list]" required>
    x component of quaternion, roll angle, rotation matrix, or quaternion array
  </ParamField>

  <ParamField query="y (Union[float, int])" type="Union[float, int]">
    y component of quaternion or pitch angle. Ignored when x is an array.
  </ParamField>

  <ParamField query="z (Union[float, int])" type="Union[float, int]">
    z component of quaternion or yaw angle. Ignored when x is an array.
  </ParamField>

  <ParamField query="w (Optional[Union[float, int]])" type="Optional[Union[float, int]]">
    w component of quaternion. When None, x, y, z are interpreted as Euler angles.
  </ParamField>
</ResponseField>

<ResponseField name="Raises">
  <ParamField query="ValueError" type="">
    If the provided arguments don't match any initialization pattern
  </ParamField>

  <ParamField query="Note" type="">
    Quaternion components are automatically normalized to ensure a unit quaternion.
  </ParamField>
</ResponseField>

### conjugate

```python theme={null}
Orientation.conjugate()
```

Return the conjugate of the quaternion (-x, -y, -z, w).

For a unit quaternion, the conjugate is its inverse.

<ResponseField name="Returns">
  <ResponseField name="Orientation" type="">
    New orientation representing the conjugate.
  </ResponseField>
</ResponseField>

### normalize

```python theme={null}
Orientation.normalize()
```

Return a normalized version of this quaternion

<ResponseField name="Returns">
  <ResponseField name="Orientation" type="">
    New orientation with normalized quaternion components
  </ResponseField>
</ResponseField>

### to\_euler

```python theme={null}
Orientation.to_euler(order: str = 'xyz') -> tuple[float, float, float]
```

Convert quaternion to Euler angles.

<ResponseField name="Arguments">
  <ParamField query="order (str)" type="str">
    Order of rotations. Defaults to "xyz". Supported orders include "xyz", "zyx", "yzx", etc.
  </ParamField>
</ResponseField>

<ResponseField name="Returns">
  <ResponseField name="returns" type="tuple[float, float, float]" />
</ResponseField>

### to\_matrix

```python theme={null}
Orientation.to_matrix() -> np.ndarray
```

Convert quaternion to a rotation matrix

<ResponseField name="Returns">
  <ResponseField name="np.ndarray" type="np.ndarray">
    3x3 rotation matrix
  </ResponseField>
</ResponseField>

### to\_axis\_angle

```python theme={null}
Orientation.to_axis_angle(degrees: bool = False) -> np.ndarray
```

Convert quaternion to axis-angle representation.

<ResponseField name="Arguments">
  <ParamField query="degrees (bool)" type="bool">
    If True, the angle is returned in degrees. Defaults to False.
  </ParamField>
</ResponseField>

<ResponseField name="Returns">
  <ResponseField name="np.ndarray" type="np.ndarray">
    3 dimensional vector which is co-directional to the axis of rotation and whose norm gives the angle of rotation.
  </ResponseField>
</ResponseField>

### to\_dict

```python theme={null}
Orientation.to_dict() -> dict
```

Serialize to dictionary for JSON transfer

<ResponseField name="Returns">
  <ResponseField name="returns" type="dict" />
</ResponseField>

### from\_dict

```python theme={null}
Orientation.from_dict(data: dict) -> 'Orientation'
```

Deserialize from dictionary

<ResponseField name="Arguments">
  <ParamField query="data (dict)" type="dict" required>
    *No description provided.*
  </ParamField>
</ResponseField>

<ResponseField name="Returns">
  <ResponseField name="returns" type="'Orientation'" />
</ResponseField>