On this page

quaternion QML Value Type

This represents an orientation in free space in quaternion form. More...

Import Statement: import QtRos2.GeometryMsgs
Status: Experimental Extension

Properties

Methods

Detailed Description

quaternion is a structured value type usable in QML. It maps directly to the geometry_msgs::msg::Quaternion ROS 2 message type.

Similar to QtQuick's quaternion value type but stored as four double components (x, y, z, w) rather than float, matching the ROS 2 wire format. Use toQuaternion() / fromQuaternion to bridge to quaternion when its math API (slerp, normalize, multiplication) is needed.

A literal value is a JavaScript object such as ({ x: 0, y: 0, z: 0, w: 1 }) (w defaults to 1). The Quaternion helper's fromEulerAngles takes ROS roll/pitch/yaw (about X/Y/Z, Z-up) in degrees; do not use QtQuick3D's Quaternion, whose argument order is pitch/yaw/roll in a Y-up frame, or the axes come out wrong when published to ROS.

Construct a quaternion in QML by assigning a JavaScript object whose keys are its component properties, by setting those properties individually, or by composing it with a factory function of the Quaternion helper type.

See also Quaternion, QuaternionPublisher, and QuaternionSubscriber.

Property Documentation

eulerAngles : vector3d

Orientation as Qt Quick 3D Euler angles in degrees, as a vector3d.

Convenience for Qt Quick 3D: the Y-up convention, single precision (QVector3D), directly bindable to Node.eulerRotation. Components are (x = pitch about X, y = yaw about the vertical Y axis, z = roll about Z). The quaternion itself is a ROS (Z-up) quaternion and is mapped into that frame with (x, y, z)scene = (y, z, x)ROS.

This is not roll/pitch/yaw. For those in the ROS convention (Z-up, double precision, usable without Qt Quick) use rpy (radians) or rpyDegrees.

rpy : vector3

Orientation as roll/pitch/yaw in radians (ROS convention).

Components are (x = roll, y = pitch, z = yaw) in radians, as a double-precision vector3. This is the ROS-native form and, unlike eulerAngles, is usable from a QCoreApplication (it does not need the Qt Quick vector3d value type).

Precision may still degrade near gimbal singularities (pitch = ±90°).

rpyDegrees : vector3

Orientation as roll/pitch/yaw in degrees, as a vector3.

Components are (x = roll about X, y = pitch about Y, z = yaw about Z) in degrees, using the ROS convention (Z-up), as a double-precision vector3. Like rpy (and unlike eulerAngles, which is the Qt Quick 3D Y-up convenience) it is usable without Qt Quick: convenient for a headless QCoreApplication consumer that works in degrees.

scalar : double

The scalar (real) component; an alias of w.

Lets a QtQuick quaternion assigned to this type map its scalar onto w (QML converts value types by name).

w : double

x : double

y : double

z : double

Method Documentation

QQuaternion toQuaternion()

Return a single-precision quaternion with the same components.

Useful for accessing quaternion's math API (slerp, normalize, multiplication). The components are copied as they are, in the ROS (Z-up) frame; they are not converted to Qt Quick 3D's Y-up frame. eulerAngles is the Y-up view.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.