Coordinate Systems

MultiSet VPS returns poses in left-handed Y-up (Unity, the default) or right-handed Y-up (ARKit, ARCore, WebXR) coordinates via the isRightHanded flag.

Overview

Every successful localization returns a 6-DoF pose: a position (x, y, z) in meters and a rotation quaternion (x, y, z, w), both expressed in the map's coordinate space.

MultiSet supports two coordinate conventions for that pose, and both are Y-up:

Convention	Flag	Ecosystem
Left-handed, Y-up (LHS)	isRightHanded: false (default)	Unity, MultiSet Quest SDK, MultiSet App
Right-handed, Y-up (RHS)	isRightHanded: true	ARKit (iOS), ARCore (Android), WebXR, Three.js, OpenGL

LHS is the map's native frame: it is how poses are stored internally, and it is what you get when the flag is omitted. Setting isRightHanded: true asks the server to convert the pose before returning it.

The two frames share the same origin, the same up axis, and the same scale. They differ by a mirror across the YZ plane: the X axis is negated. The same physical camera pose therefore has identical y and z values in both, with an opposite sign on x.

The same physical camera pose, described in both conventions

---

Which convention should I use?

Platform	Frame it works in	What to do
Unity SDK	Left-handed, Y-up	Nothing. The SDK uses the default and places content directly.
MultiSet Quest SDK	Left-handed, Y-up	Nothing. Unity based, so the default applies.
iOS native (ARKit)	Right-handed, Y-up	Send isRightHanded: true
Android native (ARCore)	Right-handed, Y-up	Send isRightHanded: true
WebXR SDK (Three.js / Needle)	Right-handed, Y-up	Send isRightHanded: true (the WebXR SDK already defaults to it)
Custom REST integration	Your choice	Pick the one that matches your renderer or engine

If your stack is right-handed but not Y-up (for example ROS, which is right-handed Z-up), request the RHS Y-up pose and apply your own axis swap on top of it.

---

Setting the flag

isRightHanded is optional on every query endpoint and defaults to false.

Endpoint	Body type	Value to send
POST /vps/map/query	JSON	"isRightHanded": true
POST /vps/map/query-form	form-data	isRightHanded=true (string)
POST /vps/map/multi-image-query	form-data	isRightHanded=true (string)
POST /vps/object/query	form-data	isRightHanded=true (string)

On the form-data endpoints every field is a string, so send the literal text true or false. Omit the field entirely to get the left-handed default.

---

Example: the same query in both conventions

Left-handed (default)

// POST /vps/map/query
{
  "mapCode": "MAP_RJFKKWQ1787J",
  "isRightHanded": false,
  "queryImage": "<base64>",
  "resolution": { "width": 960, "height": 720 },
  "cameraIntrinsics": { "fx": 669.53, "fy": 669.53, "px": 480.0, "py": 360.0 }
}

// 200 OK
{
  "poseFound": true,
  "position": { "x":  3.00, "y": 1.60, "z": 5.50 },
  "rotation": { "x": 0.00, "y":  0.38, "z": 0.00, "w": 0.92 },
  "confidence": 0.87
}

Drop this straight into a Unity Transform:

transform.position = new Vector3(3.00f, 1.60f, 5.50f);
transform.rotation = new Quaternion(0.00f, 0.38f, 0.00f, 0.92f);

Right-handed

// POST /vps/map/query
{
  "mapCode": "MAP_RJFKKWQ1787J",
  "isRightHanded": true,
  "queryImage": "<base64>",
  "resolution": { "width": 960, "height": 720 },
  "cameraIntrinsics": { "fx": 669.53, "fy": 669.53, "px": 480.0, "py": 360.0 }
}

// 200 OK, the same physical pose with a mirrored X
{
  "poseFound": true,
  "position": { "x": -3.00, "y": 1.60, "z": 5.50 },
  "rotation": { "x": 0.00, "y": -0.38, "z": 0.00, "w": 0.92 },
  "confidence": 0.87
}

Drop this straight into a Three.js object:

object.position.set(-3.00, 1.60, 5.50);
object.quaternion.set(0.00, -0.38, 0.00, 0.92);

The same request as form-data:

curl -X POST https://api.multiset.ai/v1/vps/map/query-form \
  -H "Authorization: Bearer $TOKEN" \
  -F "mapCode=MAP_RJFKKWQ1787J" \
  -F "isRightHanded=true" \
  -F "fx=669.53" -F "fy=669.53" -F "px=480.0" -F "py=360.0" \
  -F "width=960" -F "height=720" \
  -F "queryImage=@frame.jpg"

---

Converting a pose yourself

If you receive a pose in one convention and need the other, mirror it across the YZ plane: negate position.x, negate rotation.y and rotation.z, and leave everything else alone. The operation is its own inverse, so the same function converts in both directions.

JavaScript

function flipHandedness(pose) {
  return {
    position: {
      x: -pose.position.x,
      y:  pose.position.y,
      z:  pose.position.z,
    },
    rotation: {
      x:  pose.rotation.x,
      y: -pose.rotation.y,
      z: -pose.rotation.z,
      w:  pose.rotation.w,
    },
  };
}

C#

public static (Vector3 position, Quaternion rotation) FlipHandedness(
    Vector3 position, Quaternion rotation)
{
    return (
        new Vector3(-position.x, position.y, position.z),
        new Quaternion(rotation.x, -rotation.y, -rotation.z, rotation.w)
    );
}

Swift

func flipHandedness(position: SIMD3<Float>,
                    rotation: simd_quatf) -> (SIMD3<Float>, simd_quatf) {
    let p = SIMD3<Float>(-position.x, position.y, position.z)
    let r = simd_quatf(ix: rotation.imag.x,
                       iy: -rotation.imag.y,
                       iz: -rotation.imag.z,
                       r:  rotation.real)
    return (p, r)
}

Python

def flip_handedness(position, rotation):
    """position: (x, y, z), rotation: (x, y, z, w)."""
    x, y, z = position
    qx, qy, qz, qw = rotation
    return (-x, y, z), (qx, -qy, -qz, qw)

---

What isRightHanded does not change

The flag governs the pose the API returns. Several other values are always expressed in the map's native left-handed frame, no matter what you set:

Value	Frame	Notes
hintPosition	Always LHS	Convert an RHS position to LHS before sending it as a hint
hintFloorHeight	Unaffected	A Y-axis band, and Y is identical in both conventions
geoHint	Unaffected	Latitude, longitude, and altitude. The server converts it to LHS internally
GeoPose response	Unaffected	The server un-mirrors the pose before georeferencing, so GeoPose is the same either way
Georeference API local coordinates	Always LHS	Alignment points must be supplied in LHS
Simulation data capture poses	Always LHS	Convert RHS captures before uploading the manifest

The most common mistake is passing a right-handed hintPosition from a previous RHS localization result. The hint then points to the mirrored side of the map, so the search filter looks in the wrong place and localization fails or returns a poor pose. Negate x first.

Multi frame query

The multi frame query also takes a per-frame trackingPose from your local SLAM session. These are fused with the per-image estimates, so send them in the same convention you declared with isRightHanded: RHS tracking poses with isRightHanded: true, LHS tracking poses with the default. The trackingPose echoed back in the response is your input, returned unchanged.

Object Tracking query

Object Tracking uses the same flag. It applies to the detected object's pose in the camera frame: LHS by default, RHS when isRightHanded: true.