A camera-facing callout label anchored to a 3D node or position. More...
| Import Statement: | import Clayground.Canvas3D |
Label3D draws crisp, readable text (a rounded "pill" background with an optional icon) that names or annotates scene content the way technical illustrations do. It tracks either a moving anchorNode or a fixed anchorPosition, sits at that anchor plus a world-space labelOffset, and turns to face the camera every frame. The text is rendered as a Qt Quick item parented under a QtQuick3D Node (an Item2D), so it stays razor-sharp at any zoom and is never lit or shadowed.
By default the label keeps a constant on-screen pixel size (sizeMode: Label3D.Screen); switch to Label3D.World to let it scale with the scene. An optional showLeader draws a thin line from the pill edge to the anchor - the offset-callout look.
Note: Place Label3D at the scene root (a direct child of the View3D or of an untransformed node): its position is derived from anchor scene positions, and the optional leader is drawn in that same untransformed space.
Example usage:
import QtQuick3D import Clayground.Canvas3D View3D { id: view Label3D { view: view anchorNode: reactor text: "REACTOR CORE" labelOffset: Qt.vector3d(0, 40, 0) showLeader: true } }
See also PathLabel3D, LabelBatch3D, and ConnectorLayer3D.
anchorNode : QtObject |
The node the label tracks; its scene position drives placement.
When set, it takes precedence over anchorPosition and the label follows the node as it moves.
anchorPosition : vector3d |
Fixed scene position to anchor to when anchorNode is null.
camera : QtObject |
The camera the label faces. Defaults to view.camera.
distanceFade : bool |
When true, fade the label out with camera distance (Screen mode).
fadeFar : real |
Camera distance at and beyond which the label is fully transparent.
fadeNear : real |
Camera distance at and below which the label is fully opaque.
iconSource : url |
Optional icon shown left of the text. Empty hides it.
labelOffset : vector3d |
World-space offset of the pill from the anchor.
The pill is placed at anchor + labelOffset. A small upward offset is the default; larger offsets combined with showLeader produce the offset-callout look.
labelStyle : QtObject |
Grouped pill styling: colors, radius, padding, halo and font.
| Sub-property | Meaning |
|---|---|
background | Pill fill color (dark semi-transparent default). |
textColor | Text color. |
borderColor | Pill border color. |
borderWidth | Pill border width in pixels (0 = no border). |
radius | Corner radius; negative means a full pill (height/2). |
paddingH | Horizontal padding in pixels. |
paddingV | Vertical padding in pixels. |
halo | Whether the text gets an outline halo for busy backgrounds. |
haloColor | Halo color. |
fontFamily | Text font family. |
fontSize | Text pixel size. |
bold | Whether the text is bold. |
leaderStyle : QtObject |
Grouped leader-line styling: color and width (pixels).
maxScreenSize : real |
Upper clamp for the on-screen pill height in pixels (0 disables).
minScreenSize : real |
Lower clamp for the on-screen pill height in pixels (0 disables).
priority : int |
Ordering hint for the future declutter manager; higher wins.
No behaviour is attached yet: the property is shipped now so scenes can express relative label importance before the manager exists. When it arrives it will greedily keep non-overlapping labels highest-priority first, hiding lower-priority labels that would collide.
scaleQuantum : real |
Relative scale change required before the pill is re-scaled (0 disables).
In Screen size mode the pill's scale follows the camera distance, so a moving camera would re-scale - and therefore re-rasterize - the text every single frame, which reads as high-frequency shimmer. Holding the scale until it drifts past this fraction (2% by default) keeps the glyphs stable while the label still tracks depth.
screenHeight : real |
Target on-screen pill height in pixels (Screen size mode).
showLeader : bool |
When true, draw a thin line from the pill edge to the anchor.
sizeMode : int |
The active size mode, see SizeMode.
text : string |
The label text.
view : QtObject |
The enclosing View3D, used to resolve the camera, size the leader and register with the per-view label registry.
worldHeight : real |
Pill height in world units (World size mode).