Basis Permutation

The basis maps between Haply's internal coordinate system and your application's.

Haply default frame

Haply uses a right-handed coordinate system:

Axis	Direction
+X	Right
+Y	Forward
+Z	Up

How it works

A permutation string tells the service how your application's axes map to Haply's. Once set, every value the service returns (positions, velocities, forces, orientations) is expressed in your basis, and every value you send is interpreted in your basis. The conversion is automatic and bidirectional.

The string is a permutation of X, Y, Z, optionally prefixed by + or - to negate an axis.

Examples

Permutation	Meaning	Typical use
XYZ	Identity — no remapping	Haply-native apps
XZY	Swap Y and Z → your +Y is up	Y-up engines
X-YZ	Negate Y → left-handed Z-up	Unreal Engine
ZXY	Cycle all three axes	Custom frame

Interpretation

"YZX" means:

• Your X axis = Haply's Y (forward)
• Your Y axis = Haply's Z (up)
• Your Z axis = Haply's X (right)

Setting the basis

WebSocket

{
  "session": {
    "configure": {
      "basis": { "permutation": "XZY" }
    }
  }
}

HTTP

curl -X POST "http://localhost:10001/inverse3/0/config/basis?session=:0" \
     -H "Content-Type: application/json" \
     -d '{"permutation": "XZY"}'

The basis is persistent — set it once on the first message and it stays active until changed or the session ends.

Migrating from session.set_basis

The axis-sign convention changed between the legacy session.set_basis and session.configure.basis. A permutation that worked under the old command may produce an inverted transformation under the new one. Negate the axis signs where needed (e.g., X-ZY becomes XZ-Y). See the Deprecation Note for details.