FrameNode QML Type
A Qt Quick 3D Node that follows a coordinate frame in the TF tree. More...
| Import Statement: | import QtRos2.Quick3D |
| Inherits: | |
| Status: | Experimental Extension |
Properties
- frame : string
- parentFrame : string
- rosNode : Node
- valid : bool
Detailed Description
FrameNode places itself at the TF frame named by frame: its position and rotation are kept equal to the transform of frame relative to parentFrame, which by default is the frame of the nearest FrameNode ancestor. Nest FrameNodes the way the frames are nested in the robot, and give each one only its own frame name:
import QtQuick3D
import QtRos2.Core as Ros2
import QtRos2.Quick3D
Ros2.Node { id: rosNode; nodeName: "viewer" }
FrameNode {
frame: "map" // the fixed frame: left where you put it
rosNode: rosNode // inherited by the FrameNodes inside
OccupancyGridModel { } // anything drawn in map coordinates
FrameNode {
frame: "base_link" // follows map -> odom -> base_link
RobotModel { }
FrameNode {
frame: "laser" // follows base_link -> laser
LaserScanModel { }
}
}
}The transforms come from the TF buffer of rosNode, which listens to the node's tf and tf_static topics. That buffer is shared with every other FrameNode and FrameTransformer on the same Node, and is created the first time something needs it.
Frames that are not in the scene
A FrameNode's parentFrame does not need to be the frame's direct parent in the TF tree: TF composes the transforms in between. In the example above, base_link is placed relative to map even though TF relates them only through odom. Add FrameNodes only for the frames you want to draw something in.
Nodes between FrameNodes
Ordinary Nodes may sit between a FrameNode and its FrameNode ancestor; a FrameNode looks past them. Their own transforms still apply on top, which is useful for presentation, such as scaling a model, but a rotation or translation there moves everything inside away from where TF says it is.
Units and axes
TF uses meters, and ROS uses a right-handed coordinate system with Z up. FrameNode sets ROS values directly, so the units and axes of the scene inside the root FrameNode are those of ROS. To view it in Qt Quick 3D's usual Y-up, centimeter scene, put the root FrameNode inside a Node that converts once:
Node {
scale: Qt.vector3d(100, 100, 100) // meters to scene units
eulerRotation.x: -90 // ROS Z-up to Qt Quick 3D Y-up
FrameNode { frame: "map"; rosNode: rosNode; ... }
}See also FrameTransformer.
Property Documentation
frame : string
The TF frame this node follows; for example "base_link".
If the root FrameNode (one without a FrameNode ancestor and without parentFrame) has a frame, it is not moved: it defines where that frame is in the scene, and the FrameNodes inside are positioned relative to it.
A FrameNode without a frame is not moved either, and FrameNodes inside it look past it for the frame to be positioned relative to. It can still provide the rosNode they inherit.
parentFrame : string
The frame that frame is positioned relative to. By default this is the frame of the nearest FrameNode ancestor that has one, which is what a scene that mirrors the TF tree needs. Set it to override that; reset it with undefined to go back to the default.
Reading this property returns the frame in effect. It is empty for a root FrameNode, which keeps the position and rotation it was given.
rosNode : Node
The ROS 2 Node whose TF tree this FrameNode reads. By default it is inherited from the nearest FrameNode ancestor, so it normally needs to be set only on the root FrameNode. Reset it with undefined to go back to the inherited one.
valid : bool [read-only]
true when the node's position and rotation reflect the transform from parentFrame to frame: that is, once that transform has been received. It becomes false if the transform can no longer be resolved, and the node then stays where it was last placed. A root FrameNode, and one without a frame, is always valid.
Bind visible to it to hide a part of the scene until TF has placed it:
FrameNode {
frame: "base_link"
visible: valid
RobotModel { }
}© 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.