Introduction to coordinate spaces
Understand how Simulation Pro's typed coordinate wrappers prevent coordinate frame mismatches.
Unity and Robot Operating System (ROS) use different coordinate conventions. Simulation Pro provides compile-time-checked wrappers (Vector3<C> and Quaternion<C>) that make it impossible to unintentionally mix values from different frames.
Typed wrappers
Simulation Pro provides two generic wrappers, Vector3<C> and Quaternion<C>, that tag a value with its coordinate space C at compile time.
Vector3<C>
Wrap a Unity Vector3 in a coordinate space type to convert it and read its components in that frame.
// Convert a Unity Vector3 (RUF) into FLU:
Vector3<FLU> positionFLU = new Vector3<FLU>(transform.position);
// Read the x, y, z components (in FLU frame):
float forward = positionFLU.x;
// Convert back to Unity Vector3:
Vector3 unityPosition = positionFLU.toUnity;
// Use the extension method for a more fluent style:
Vector3<FLU> vel = rigidbody.velocity.To<FLU>();
Quaternion<C>
Quaternion<C> works the same way as Vector3<C>, but for rotations.
// Convert a Unity Quaternion (RUF) to FLU:
Quaternion<FLU> rotFLU = new Quaternion<FLU>(transform.rotation);
// Convert back to Unity Quaternion:
Quaternion unityRot = rotFLU.toUnity;
// Extension method:
Quaternion<FLU> q = transform.rotation.To<FLU>();
Converting between frames
Call To<C>() on a typed value to convert it directly to another coordinate space, without going through Unity's native frame first.
// From FLU to NED:
Vector3<NED> posNED = positionFLU.To<NED>();
// From NED to FLU:
Vector3<FLU> posFLU2 = posNED.To<FLU>();
ICoordinateSpace
All coordinate space types implement ICoordinateSpace, which defines conversion to and from the Unity (RUF) frame:
public interface ICoordinateSpace
{
Vector3 ConvertFromRUF(Vector3 v);
Vector3 ConvertToRUF(Vector3 v);
Quaternion ConvertFromRUF(Quaternion q);
Quaternion ConvertToRUF(Quaternion q);
Vector3 ConvertAngularVelocityFromRUF(Vector3 angularVelocity);
Vector3 ConvertAngularVelocityToRUF(Vector3 angularVelocity);
}
You can implement ICoordinateSpace to define a custom frame.
CompassDirection
NED and ENU require knowing which Unity world-axis points north. Configure this once per project:
CompassDirection.UnityZAxisDirection = CardinalDirection.North; // default
The setting is persisted as a ScriptableObject at Assets/Resources/CompassDirectionSettings.asset. Tests that trigger CompassDirection.GetOrCreateSettings() should clean up this asset in [OneTimeTearDown].
The CompassDirectionExtensions class provides helpers to convert a CardinalDirection into a Unity world-space direction vector or a yaw angle:
Vector3 northDir = CardinalDirection.North.ToWorldDirection();
float northYaw = CardinalDirection.North.ToUnityYawDegrees();