Changes Quaternion convention from WXYZ to XYZW (#4437)

# Description

Changes the quaternion convention in IsaacLab to match that of:
- ROS
- PhysX
- Newton
- Scipy
- Low level USD

Fixes isaac-sim/IsaacLab-Internal#744 

This PR brings massive changes throughout the code base. Almost all
users should expect their code to be impacted by these changes. We
provide a tool that should help users navigate these changes.

`./scripts/tools/find_quaternions.py` provides users with an automated
script to search throughout the code base some quaternions that do not
differ between the current code and a given commit. This can be used to
track if your code has changed the order of its hard-coded quaternions.

For instance running the following will show all the quaternions that
might need to be updated inside your extension. The dry-run flag will
make it so that the script does not attempt to modify the quaternions.
```
./scripts/tools/find_quaternions.py --path PATH_TO_YOUR_EXTENSION --all-quats --fix --context 4 --dry-run
```
If you want to modify the quaternions the script comes with an
interactive mode where it prompts you with changes to be made, to do so
remove the `--dry-run` flag:
```
./scripts/tools/find_quaternions.py --path PATH_TO_YOUR_EXTENSION --all-quats --fix --context 4
```
The `--context` flag provides more or less context before and after the
line where a quaternion was found.


Here is a sample of the interactive mode:
```shell
Searching 968 Python, 11 JSON, and 6 RST files...
Comparing against: main
Found 178 files changed from main

Found 69 potential quaternions to review:

====================================================================================================

────────────────────────────────────────────────────────────────────────────────
📍 source/isaaclab_assets/isaaclab_assets/robots/anymal.py:173 [AMBIGUOUS]
────────────────────────────────────────────────────────────────────────────────
     169 | # Configuration - Sensors.
     170 | ##
     171 | 
     172 | ANYMAL_LIDAR_CFG = VELODYNE_VLP_16_RAYCASTER_CFG.replace(
>>>  173 |     offset=RayCasterCfg.OffsetCfg(pos=(-0.310, 0.000, 0.159), rot=(0.0, 0.0, 0.0, 1.0))
     174 | )
     175 | """Configuration for the Velodyne VLP-16 sensor mounted on the ANYmal robot's base."""
────────────────────────────────────────────────────────────────────────────────
  Change: [0.0, 0.0, 0.0, 1.0] → [0.0, 0.0, 1.0, 0.0]
  Result: offset=RayCasterCfg.OffsetCfg(pos=(-0.310, 0.000, 0.159), rot=(0.0, 0.0, 1.0, 0.0))
Apply this fix? [Y/n/a/q]: Y
  ✅ Fixed!

────────────────────────────────────────────────────────────────────────────────
📍 source/isaaclab_mimic/test/test_curobo_planner_franka.py:42 [AMBIGUOUS]
────────────────────────────────────────────────────────────────────────────────
      38 | 
      39 | # Predefined EE goals for the test
      40 | # Each entry is a tuple of: (goal specification, goal ID)
      41 | predefined_ee_goals_and_ids = [
>>>   42 |     ({"pos": [0.70, -0.25, 0.25], "quat": [0.0, 0.707, 0.0, 0.707]}, "Behind wall, left"),
      43 |     ({"pos": [0.70, 0.25, 0.25], "quat": [0.0, 0.707, 0.0, 0.707]}, "Behind wall, right"),
      44 |     ({"pos": [0.65, 0.0, 0.45], "quat": [1.0, 0.0, 0.0, 0.0]}, "Behind wall, center, high"),
      45 |     ({"pos": [0.80, -0.15, 0.35], "quat": [0.0, 0.5, 0.0, 0.866]}, "Behind wall, far left"),
      46 |     ({"pos": [0.80, 0.15, 0.35], "quat": [0.0, 0.5, 0.0, 0.866]}, "Behind wall, far right"),
────────────────────────────────────────────────────────────────────────────────
  Change: [0.0, 0.707, 0.0, 0.707] → [0.707, 0.0, 0.707, 0.0]
  Result: ({"pos": [0.70, -0.25, 0.25], "quat": [0.707, 0.0, 0.707, 0.0]}, "Behind wall, left"),
Apply this fix? [Y/n/a/q]: Y
  ✅ Fixed!

────────────────────────────────────────────────────────────────────────────────
📍 source/isaaclab_mimic/test/test_curobo_planner_franka.py:43 [AMBIGUOUS]
────────────────────────────────────────────────────────────────────────────────
      39 | # Predefined EE goals for the test
      40 | # Each entry is a tuple of: (goal specification, goal ID)
      41 | predefined_ee_goals_and_ids = [
      42 |     ({"pos": [0.70, -0.25, 0.25], "quat": [0.707, 0.0, 0.707, 0.0]}, "Behind wall, left"),
>>>   43 |     ({"pos": [0.70, 0.25, 0.25], "quat": [0.0, 0.707, 0.0, 0.707]}, "Behind wall, right"),
      44 |     ({"pos": [0.65, 0.0, 0.45], "quat": [1.0, 0.0, 0.0, 0.0]}, "Behind wall, center, high"),
      45 |     ({"pos": [0.80, -0.15, 0.35], "quat": [0.0, 0.5, 0.0, 0.866]}, "Behind wall, far left"),
      46 |     ({"pos": [0.80, 0.15, 0.35], "quat": [0.0, 0.5, 0.0, 0.866]}, "Behind wall, far right"),
      47 | ]
────────────────────────────────────────────────────────────────────────────────
  Change: [0.0, 0.707, 0.0, 0.707] → [0.707, 0.0, 0.707, 0.0]
  Result: ({"pos": [0.70, 0.25, 0.25], "quat": [0.707, 0.0, 0.707, 0.0]}, "Behind wall, right"),
Apply this fix? [Y/n/a/q]: Y
  ✅ Fixed!
```


## Type of change

- Breaking change (existing functionality will not work without user
modification)
- Documentation update


## Checklist

- [x] I have read and understood the [contribution
guidelines](https://isaac-sim.github.io/IsaacLab/main/source/refs/contributing.html)
- [x] I have run the [`pre-commit` checks](https://pre-commit.com/) with
`./isaaclab.sh --format`
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] I have updated the changelog and the corresponding version in the
extension's `config/extension.toml` file
- [x] I have added my name to the `CONTRIBUTORS.md` or my name already
exists there

---------

Signed-off-by: Kelly Guo <[email protected]>
Co-authored-by: Kelly Guo <[email protected]>

Author: AntoineRichard

CONTRIBUTORS.md

@@ -19,6 +19,7 @@ Guidelines for modifications:
 
 ---
 
+* Antoine Richard
 * Antonio Serrano-Muñoz
 * Ben Johnston
 * Brian McCann

docs/index.rst

@@ -150,6 +150,7 @@ Table of Contents
    source/migration/migrating_from_isaacgymenvs
    source/migration/migrating_from_omniisaacgymenvs
    source/migration/migrating_from_orbit
+   source/migration/migrating_to_isaaclab_3-0
 
 .. toctree::
    :maxdepth: 1

docs/source/how-to/make_fixed_prim.rst

@@ -100,7 +100,7 @@ For instance, to spawn an ANYmal robot and make it static in the simulation worl
         ),
     )
     anymal_spawn_cfg.func(
-        "/World/ANYmal", anymal_spawn_cfg, translation=(0.0, 0.0, 0.8), orientation=(1.0, 0.0, 0.0, 0.0)
+        "/World/ANYmal", anymal_spawn_cfg, translation=(0.0, 0.0, 0.8), orientation=(0.0, 0.0, 0.0, 1.0)
     )
 
 

docs/source/migration/migrating_to_isaaclab_3-0.rst

@@ -0,0 +1,289 @@
+.. _migrating-to-isaaclab-3-0:
+
+Migrating to IsaacLab 3.0
+=========================
+
+.. currentmodule:: isaaclab
+
+IsaacLab 3.0 introduces a significant change to quaternion ordering throughout the codebase.
+This guide explains what changed, why it matters, and how to update your code.
+
+
+What Changed: Quaternion Format
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**The quaternion format changed from WXYZ to XYZW.**
+
++------------------+----------------------------------+----------------------------------+
+| Component        | Old Format (WXYZ)                | New Format (XYZW)                |
++==================+==================================+==================================+
+| Order            | ``(w, x, y, z)``                 | ``(x, y, z, w)``                 |
++------------------+----------------------------------+----------------------------------+
+| Identity         | ``(1.0, 0.0, 0.0, 0.0)``         | ``(0.0, 0.0, 0.0, 1.0)``         |
++------------------+----------------------------------+----------------------------------+
+
+
+Why This Change?
+----------------
+
+The new XYZW format aligns with:
+
+- **Warp**: NVIDIA's spatial computing framework
+- **PhysX**: PhysX physics engine
+- **Newton**: Newton multi-solver framework
+
+This alignment removes the need for internal quaternion conversions, making the code simpler,
+faster, and less error-prone.
+
+
+What You Need to Update
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Any hard-coded quaternion values in your code need to be converted from WXYZ to XYZW.
+This includes:
+
+1. **Configuration files** - ``rot`` parameters in asset configs
+2. **Task definitions** - Goal poses, initial states
+3. **Controller parameters** - Target orientations
+4. **Documentation** - Code examples with quaternions
+
+Also, if you were relying on the :func:`~isaaclab.utils.math.convert_quat` function to convert quaternions, this should
+no longer be needed. (This would happen if you were pulling values from the views directly.)
+
+Example: Updating Asset Configuration
+-------------------------------------
+
+**Before (WXYZ):**
+
+.. code-block:: python
+
+   from isaaclab.assets import AssetBaseCfg
+
+   cfg = AssetBaseCfg(
+       init_state=AssetBaseCfg.InitialStateCfg(
+           pos=(0.0, 0.0, 0.5),
+           rot=(1.0, 0.0, 0.0, 0.0),  # OLD: w, x, y, z
+       ),
+   )
+
+**After (XYZW):**
+
+.. code-block:: python
+
+   from isaaclab.assets import AssetBaseCfg
+
+   cfg = AssetBaseCfg(
+       init_state=AssetBaseCfg.InitialStateCfg(
+           pos=(0.0, 0.0, 0.5),
+           rot=(0.0, 0.0, 0.0, 1.0),  # NEW: x, y, z, w
+       ),
+   )
+
+
+Using the Quaternion Finder Tool
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+We provide a tool to help you find and fix quaternions in your codebase automatically. This is not a bulletproof tool,
+but it should help you find most of the quaternions that need to be updated. You *should* review the results manually.
+
+.. warning::
+  Do not run the tool on the whole codebase! If you run the tool on our own packages (isaaclab, or isaaclab_tasks for
+  instance) it will find all the quaternions that we already converted. This tool is only meant to be used on your own
+  codebase with no overlap with our own packages.
+
+Finding Quaternions
+-------------------
+
+Run the tool to scan your code for potential quaternions:
+
+.. code-block:: bash
+
+   # Scan the 'source' directory (default)
+   python scripts/tools/find_quaternions.py
+
+   # Scan a specific path
+   python scripts/tools/find_quaternions.py --path my_project/
+
+   # Compare against a different branch
+   python scripts/tools/find_quaternions.py --base develop
+
+.. tip::
+  We recommend always running the tool with a custom base branch *and* a specific path.
+
+
+The tool will show you:
+
+- Quaternions that haven't been updated (marked as ``UNCHANGED``)
+- Whether each looks like a WXYZ identity quaternion (``WXYZ_IDENTITY``)
+- Whether the format is likely WXYZ (``LIKELY_WXYZ``)
+
+
+Understanding the Output
+------------------------
+
+.. code-block:: text
+
+   my_project/robot_cfg.py:42:8 ⚠ UNCHANGED [WXYZ_IDENTITY]
+     Values: [1.0, 0.0, 0.0, 0.0]
+     Source: rot=(1.0, 0.0, 0.0, 0.0),
+
+This tells you:
+
+- **File and line**: ``my_project/robot_cfg.py:42``
+- **Status**: ``UNCHANGED`` means this line hasn't been modified yet
+- **Flag**: ``WXYZ_IDENTITY`` means it's the identity quaternion in old WXYZ format
+- **Values**: The actual quaternion values found
+- **Source**: The line of code for context
+
+
+Filtering Results
+-----------------
+
+Focus on specific types of quaternions:
+
+.. code-block:: bash
+
+   # Only show identity quaternions [1, 0, 0, 0]
+   python scripts/tools/find_quaternions.py --check-identity
+
+   # Only show quaternions likely in WXYZ format
+   python scripts/tools/find_quaternions.py --likely-wxyz
+
+   # Show ALL potential quaternions (ignore format heuristics)
+   python scripts/tools/find_quaternions.py --all-quats
+
+
+Fixing Quaternions Automatically
+--------------------------------
+
+The tool can automatically convert quaternions from WXYZ to XYZW:
+
+.. code-block:: bash
+
+   # Interactive mode: prompts before each fix
+   python scripts/tools/find_quaternions.py --fix
+
+   # Only fix identity quaternions (safest option)
+   python scripts/tools/find_quaternions.py --fix-identity-only
+
+   # Preview changes without applying them
+   python scripts/tools/find_quaternions.py --fix --dry-run
+
+   # Apply all fixes without prompting
+   python scripts/tools/find_quaternions.py --fix --force
+
+
+Interactive Fix Example
+-----------------------
+
+When running with ``--fix``, you'll see something like:
+
+.. code-block:: text
+
+   ────────────────────────────────────────────────────────────────────────────────
+   📍 my_project/robot_cfg.py:42 [WXYZ_IDENTITY]
+   ────────────────────────────────────────────────────────────────────────────────
+        40 |     init_state=AssetBaseCfg.InitialStateCfg(
+        41 |         pos=(0.0, 0.0, 0.5),
+   >>>  42 |         rot=(1.0, 0.0, 0.0, 0.0),
+        43 |     ),
+        44 | )
+   ────────────────────────────────────────────────────────────────────────────────
+     Change: [1.0, 0.0, 0.0, 0.0] → [0.0, 0.0, 0.0, 1.0]
+     Result: rot=(0.0, 0.0, 0.0, 1.0),
+   Apply this fix? [Y/n/a/q]:
+
+Options:
+
+- **Y** (yes): Apply this fix
+- **n** (no): Skip this one
+- **a** (all): Apply all remaining fixes without asking
+- **q** (quit): Stop fixing
+
+
+How the Tool Works
+------------------
+
+The tool uses several techniques to find quaternions:
+
+1. **Python files**: Parses the code using AST (Abstract Syntax Tree) to find
+   4-element tuples and lists with numeric values.
+
+2. **JSON files**: Uses regex to find 4-element arrays.
+
+3. **RST documentation**: Searches for quaternion-like patterns in docs.
+
+To identify if something is a quaternion, the tool checks:
+
+- Is it exactly 4 numeric values?
+- Does the sum of squares ≈ 1? (unit quaternion property)
+- Does it match known patterns like identity quaternions?
+
+To determine if it's in WXYZ format:
+
+- Is the first value 1.0 and rest are 0? (WXYZ identity)
+- Is the first value a common cos(θ/2) value like 0.707, 0.866, etc.?
+- Is the pattern consistent with first-element being the scalar part?
+
+
+Best Practices for Migration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. **Start with a clean git state** - Commit your work before running fixes.
+
+2. **Run the tool first without ``--fix``** - Review what will be changed.
+
+3. **Fix identity quaternions first** - They're the most common and safest:
+
+   .. code-block:: bash
+
+      python scripts/tools/find_quaternions.py --fix-identity-only
+
+4. **Review non-identity quaternions manually** - Some 4-element lists might
+   not be quaternions (e.g., RGBA colors, bounding boxes).
+
+5. **Test your code** - Run your simulations to verify everything works correctly.
+
+6. **Check documentation** - Update any docs or comments that mention quaternion format.
+
+API Changes
+~~~~~~~~~~~
+
+The ``convert_quat`` function has been removed
+----------------------------------------------
+
+Previously, IsaacLab had a utility function to convert between quaternion formats:
+
+.. code-block:: python
+
+   # OLD - No longer needed
+   from isaaclab.utils.math import convert_quat
+   quat_xyzw = convert_quat(quat_wxyz, "xyzw")
+
+Since everything now uses XYZW natively, this function is no longer needed.
+If you were using it, simply remove the conversion calls.
+
+
+Math utility functions now expect XYZW
+--------------------------------------
+
+All quaternion functions in :mod:`isaaclab.utils.math` now expect and return
+quaternions in XYZW format:
+
+- :func:`~isaaclab.utils.math.quat_mul`
+- :func:`~isaaclab.utils.math.quat_apply`
+- :func:`~isaaclab.utils.math.quat_from_euler_xyz`
+- :func:`~isaaclab.utils.math.euler_xyz_from_quat`
+- :func:`~isaaclab.utils.math.quat_from_matrix`
+- :func:`~isaaclab.utils.math.matrix_from_quat`
+- And all other quaternion utilities
+
+
+Need Help?
+~~~~~~~~~~
+
+If you encounter issues during migration:
+
+1. Check the `IsaacLab GitHub Issues <https://github.com/isaac-sim/IsaacLab/issues>`_
+2. Review the `CHANGELOG <https://github.com/isaac-sim/IsaacLab/blob/main/source/isaaclab/docs/CHANGELOG.rst>`_
+3. Join the community on `Discord <https://discord.gg/nvidiaomniverse>`_

scripts/benchmarks/benchmark_view_comparison.py

@@ -73,7 +73,6 @@
 from isaacsim.core.simulation_manager import SimulationManager
 
 import isaaclab.sim as sim_utils
-import isaaclab.utils.math as math_utils
 from isaaclab.sim.views import XformPrimView
 
 
@@ -168,8 +167,6 @@ def benchmark_view(view_type: str, num_iterations: int) -> tuple[dict[str, float
             transforms = view.get_transforms()
             positions = transforms[:, :3]
             orientations = transforms[:, 3:7]
-            # Convert quaternion from xyzw to wxyz
-            orientations = math_utils.convert_quat(orientations, to="wxyz")
     timing_results["get_world_poses"] = (time.perf_counter() - start_time) / num_iterations
 
     # Store initial world poses
@@ -184,9 +181,7 @@ def benchmark_view(view_type: str, num_iterations: int) -> tuple[dict[str, float
         if view_type in ("xform", "xform_fabric"):
             view.set_world_poses(new_positions, orientations)
         else:  # physx
-            # Convert quaternion from wxyz to xyzw for PhysX
-            orientations_xyzw = math_utils.convert_quat(orientations, to="xyzw")
-            new_transforms = torch.cat([new_positions, orientations_xyzw], dim=-1)
+            new_transforms = torch.cat([new_positions, orientations], dim=-1)
             view.set_transforms(new_transforms, indices=all_indices)
     timing_results["set_world_poses"] = (time.perf_counter() - start_time) / num_iterations
 
@@ -196,7 +191,7 @@ def benchmark_view(view_type: str, num_iterations: int) -> tuple[dict[str, float
     else:  # physx
         transforms_after = view.get_transforms()
         positions_after_set = transforms_after[:, :3]
-        orientations_after_set = math_utils.convert_quat(transforms_after[:, 3:7], to="wxyz")
+        orientations_after_set = transforms_after[:, 3:7]
     computed_results["world_positions_after_set"] = positions_after_set.clone()
     computed_results["world_orientations_after_set"] = orientations_after_set.clone()
 

scripts/demos/bin_packing.py

@@ -171,9 +171,7 @@ def reset_object_collections(
 
         # Compose new orientations by applying the sampled euler noise in quaternion space.
         orientations_delta = math_utils.quat_from_euler_xyz(samples[..., 3], samples[..., 4], samples[..., 5])
-        orientations = math_utils.convert_quat(orientations, to="wxyz")
         orientations = math_utils.quat_mul(orientations, orientations_delta)
-        orientations = math_utils.convert_quat(orientations, to="xyzw")
 
     # velocities
     new_velocities = sel_view_states[:, 7:13]
@@ -239,7 +237,7 @@ def build_grocery_defaults(
     grid_y, grid_x = torch.meshgrid(y, x, indexing="ij")
     grid_z = CACHE_HEIGHT * torch.ones_like(grid_x)
     # We can then create the poses for the cached groceries.
-    ref_quat = torch.tensor([[1.0, 0.0, 0.0, 0.0]], device=device).repeat(num_x_objects * num_y_objects, 1)
+    ref_quat = torch.tensor([[0.0, 0.0, 0.0, 1.0]], device=device).repeat(num_x_objects * num_y_objects, 1)
     positions = torch.stack((grid_x.flatten(), grid_y.flatten(), grid_z.flatten()), dim=-1)
     poses = torch.cat((positions, ref_quat), dim=-1)
     # Duplicate across environments, cap at max_num_objects

scripts/environments/state_machine/lift_cube_sm.py

@@ -221,10 +221,6 @@ def reset_idx(self, env_ids: Sequence[int] = None):
 
     def compute(self, ee_pose: torch.Tensor, object_pose: torch.Tensor, des_object_pose: torch.Tensor) -> torch.Tensor:
         """Compute the desired state of the robot's end-effector and the gripper."""
-        # convert all transformations from (w, x, y, z) to (x, y, z, w)
-        ee_pose = ee_pose[:, [0, 1, 2, 4, 5, 6, 3]]
-        object_pose = object_pose[:, [0, 1, 2, 4, 5, 6, 3]]
-        des_object_pose = des_object_pose[:, [0, 1, 2, 4, 5, 6, 3]]
 
         # convert to warp
         ee_pose_wp = wp.from_torch(ee_pose.contiguous(), wp.transform)
@@ -250,10 +246,8 @@ def compute(self, ee_pose: torch.Tensor, object_pose: torch.Tensor, des_object_p
             device=self.device,
         )
 
-        # convert transformations back to (w, x, y, z)
-        des_ee_pose = self.des_ee_pose[:, [0, 1, 2, 6, 3, 4, 5]]
         # convert to torch
-        return torch.cat([des_ee_pose, self.des_gripper_state.unsqueeze(-1)], dim=-1)
+        return torch.cat([self.des_ee_pose, self.des_gripper_state.unsqueeze(-1)], dim=-1)
 
 
 def main():