QCustom3DItem Class | Qt Graphs | Qt 6.12.0
Description: The QCustom3DItem class adds a custom item to a graph.
Keywords: class

- Qt 6.12
- Qt Graphs
- C++ Classes
- QtGraphs
- QCustom3DItem
- Qt Graphs | Commercial or GPLv3

# QCustom3DItem Class

The QCustom3DItem class adds a custom item to a graph. More...

Header: | `#include <QCustom3DItem>`
CMake: | `find_package(Qt6 REQUIRED COMPONENTS Graphs)` `target_link_libraries(mytarget PRIVATE Qt6::Graphs)`
qmake: | `QT += graphs`
In QML: | Custom3DItem
Inherits: | QObject
Inherited By: | QCustom3DLabel and QCustom3DVolume

- List of all members, including inherited members
- QCustom3DItem is part of Qt Graphs C++ Classes for 3D.

## Properties

meshFile : QString position : QVector3D positionAbsolute : bool rotation : QQuaternion `(since 6.11)` rotationAbsolute : bool | scaling : QVector3D scalingAbsolute : bool shadowCasting : bool textureFile : QString visible : bool

## Public Functions

| QCustom3DItem(QObject *parent = nullptr)
| QCustom3DItem(const QString &meshFile, QVector3D position, QVector3D scaling, const QQuaternion &rotation, const QImage &texture, QObject *parent = nullptr)
virtual | ~QCustom3DItem() override
bool | isPositionAbsolute() const
bool | isRotationAbsolute() const
bool | isScalingAbsolute() const
bool | isShadowCasting() const
bool | isVisible() const
QString | meshFile() const
QVector3D | position() const
QQuaternion | rotation()
QVector3D | scaling() const
void | setMeshFile(const QString &meshFile)
void | setPosition(QVector3D position)
void | setPositionAbsolute(bool positionAbsolute)
void | setRotation(const QQuaternion &rotation)
void | setRotationAbsolute(bool rotationAbsolute)
void | setRotationAxisAndAngle(QVector3D axis, float angle)
void | setScaling(QVector3D scaling)
void | setScalingAbsolute(bool scalingAbsolute)
void | setShadowCasting(bool enabled)
void | setTextureFile(const QString &textureFile)
void | setTextureImage(const QImage &textureImage)
void | setVisible(bool visible)
QString | textureFile() const

## Signals

void | meshFileChanged(const QString &meshFile)
void | positionAbsoluteChanged(bool positionAbsolute)
void | positionChanged(QVector3D position)
void | rotationAbsoluteChanged(bool newRotationAbsolute)
void | rotationChanged(const QQuaternion &rotation)
void | scalingAbsoluteChanged(bool scalingAbsolute)
void | scalingChanged(QVector3D scaling)
void | shadowCastingChanged(bool shadowCasting)
void | textureFileChanged(const QString &textureFile)
void | visibleChanged(bool visible)

## Detailed Description

A custom item has a custom mesh, position, scaling, rotation, and an optional texture.

See also Q3DGraphsWidgetItem::addCustomItem().

## Property Documentation

### meshFile : QString

This property holds the item mesh file name.

The item in the file must be in mesh format. The other types can be converted by Balsam asset import tool. The mesh files are recommended to include vertices, normals, and UVs.

Access functions:

QString | meshFile() const
void | setMeshFile(const QString &meshFile)

Notifier signal:

void | meshFileChanged(const QString &meshFile)

### position : QVector3D

This property holds the item position as a QVector3D.

Defaults to `QVector3D(0.0, 0.0, 0.0)`.

Item position is specified either in data coordinates or in absolute coordinates, depending on the positionAbsolute property. When using absolute coordinates, values between `-1.0...1.0` are within axis ranges.

Note: Items positioned outside any axis range are not rendered if positionAbsolute is `false`, unless the item is a QCustom3DVolume that would be partially visible and scalingAbsolute is also `false`. In that case, the visible portion of the volume will be rendered.

Access functions:

QVector3D | position() const
void | setPosition(QVector3D position)

Notifier signal:

void | positionChanged(QVector3D position)

See also positionAbsolute.

### positionAbsolute : bool

This property holds whether item position is to be handled in data coordinates or in absolute coordinates.

Defaults to `false`. Items with absolute coordinates will always be rendered, whereas items with data coordinates are only rendered if they are within axis ranges.

Access functions:

bool | isPositionAbsolute() const
void | setPositionAbsolute(bool positionAbsolute)

Notifier signal:

void | positionAbsoluteChanged(bool positionAbsolute)

See also position.

### rotation : QQuaternion

This property holds the item rotation as a QQuaternion.

Defaults to `QQuaternion(0.0, 0.0, 0.0, 0.0)`.

Access functions:

QQuaternion | rotation()
void | setRotation(const QQuaternion &rotation)

Notifier signal:

void | rotationChanged(const QQuaternion &rotation)

### `[since 6.11]` rotationAbsolute : bool

This property holds whether item rotation is to be handled in data axis coordinates or in absolute coordinates.

Defines whether item rotation is to be handled in data values or in absolute values. Defaults to `true`. Items with absolute rotation will be rotated with the default coordinates, regardless of axis. Items with data rotation will rotate according to the axis coordinates.

This enumeration was introduced in Qt 6.11.

Access functions:

bool | isRotationAbsolute() const
void | setRotationAbsolute(bool rotationAbsolute)

Notifier signal:

void | rotationAbsoluteChanged(bool newRotationAbsolute)

See also rotation.

### scaling : QVector3D

This property holds the item scaling as a QVector3D.

Defaults to `QVector3D(0.1, 0.1, 0.1)`.

Item scaling is either in data values or in absolute values, depending on the scalingAbsolute property. The default vector interpreted as absolute values sets the item to 10% of the height of the graph, provided the item mesh is normalized and the graph aspect ratios have not been changed from the defaults.

Note: In Qt 6.8 models were incorrectly assumed to be scaled to a size of 1 (-0.5...0.5) by default, when they in reality are scaled to the size of 2 (-1...1). Because of this, all custom items from Qt 6.9 onwards are twice the size compared to Qt 6.8

Access functions:

QVector3D | scaling() const
void | setScaling(QVector3D scaling)

Notifier signal:

void | scalingChanged(QVector3D scaling)

See also scalingAbsolute.

### scalingAbsolute : bool

This property holds whether item scaling is to be handled in data values or in absolute values.

Defaults to `true`.

Items with absolute scaling will be rendered at the same size, regardless of axis ranges. Items with data scaling will change their apparent size according to the axis ranges. If positionAbsolute is `true`, this property is ignored and scaling is interpreted as an absolute value. If the item has rotation, the data scaling is calculated on the unrotated item. Similarly, for QCustom3DVolume items, the range clipping is calculated on the unrotated item.

Note: Only absolute scaling is supported for QCustom3DLabel items or for custom items used in polar graphs.

Note: The custom item's mesh must be normalized to the range `[-1 ,1]`, or the data scaling will not be accurate.

Access functions:

bool | isScalingAbsolute() const
void | setScalingAbsolute(bool scalingAbsolute)

Notifier signal:

void | scalingAbsoluteChanged(bool scalingAbsolute)

See also scaling and positionAbsolute.

### shadowCasting : bool

This property holds whether shadow casting for the item is enabled.

Defaults to `true`. If `false`, the item does not cast shadows regardless of Q3DGraphsWidgetItem::ShadowQuality.

Access functions:

bool | isShadowCasting() const
void | setShadowCasting(bool enabled)

Notifier signal:

void | shadowCastingChanged(bool shadowCasting)

### textureFile : QString

This property holds the texture file name for the item.

If both this property and the texture image are unset, a solid gray texture will be used.

Note: To conserve memory, the QImage loaded from the file is cleared after a texture is created.

Access functions:

QString | textureFile() const
void | setTextureFile(const QString &textureFile)

Notifier signal:

void | textureFileChanged(const QString &textureFile)

### visible : bool

This property holds the visibility of the item.

Defaults to `true`.

Access functions:

bool | isVisible() const
void | setVisible(bool visible)

Notifier signal:

void | visibleChanged(bool visible)

## Member Function Documentation

### `[explicit]` QCustom3DItem::QCustom3DItem(QObject *parent = nullptr)

Constructs a custom 3D item with the specified parent.

### `[explicit]` QCustom3DItem::QCustom3DItem(const QString &meshFile, QVector3D position, QVector3D scaling, const QQuaternion &rotation, const QImage &texture, QObject *parent = nullptr)

Constructs a custom 3D item with the specified meshFile, position, scaling, rotation, texture image, and optional parent.

### `[override virtual noexcept]` QCustom3DItem::~QCustom3DItem()

Deletes the custom 3D item.

### `[invokable]` void QCustom3DItem::setRotationAxisAndAngle(QVector3D axis, float angle)

A convenience function to construct the rotation quaternion from axis and angle.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also rotation.

### void QCustom3DItem::setTextureImage(const QImage &textureImage)

Sets the value of textureImage as a QImage for the item. The texture defaults to solid gray.

Note: To conserve memory, the given QImage is cleared after a texture is created.