- Qt 6.12
- Qt Graphs
- QML Types
- QtGraphs
- Custom3DItem
- Qt Graphs | Commercial or GPLv3

# Custom3DItem QML Type

Adds a custom item to a graph. More...

Import Statement: | `import QtGraphs`
In C++: | QCustom3DItem
Inherited By: | Custom3DLabel and Custom3DVolume

- List of all members, including inherited members
- Custom3DItem is part of Qt Graphs QML Types for 3D.

## Properties

- meshFile : string
- position : vector3d
- positionAbsolute : bool
- rotation : quaternion
- rotationAbsolute : bool `(since 6.11)`
- scaling : vector3d
- scalingAbsolute : bool
- shadowCasting : bool
- textureFile : string
- visible : bool

## Signals

- meshFileChanged(string meshFile)
- positionAbsoluteChanged(bool positionAbsolute)
- positionChanged(vector3d position)
- rotationChanged(quaternion rotation)
- scalingAbsoluteChanged(bool scalingAbsolute)
- scalingChanged(vector3d scaling)
- shadowCastingChanged(bool shadowCasting)
- textureFileChanged(string textureFile)
- visibleChanged(bool visible)

## Methods

- void setRotationAxisAndAngle(vector3d axis, real angle)

## Detailed Description

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

## Property Documentation

### meshFile : string

The item mesh file name. The item in the file must be mesh format. The mesh files are recommended to include vertices, normals, and UVs.

### position : vector3d

The item position as a vector3d. Defaults to `vector3d(0.0, 0.0, 0.0)`.

Item position is specified either in data coordinates or in absolute coordinates, depending on the value of 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 Custom3DVolume that would be partially visible and scalingAbsolute is also `false`. In that case, the visible portion of the volume will be rendered.

See also positionAbsolute and scalingAbsolute.

### positionAbsolute : bool

Defines 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.

See also position.

### rotation : quaternion

The item rotation as a quaternion. Defaults to `quaternion(0.0, 0.0, 0.0, 0.0)`.

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

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 property was introduced in Qt 6.11.

See also rotation.

### scaling : vector3d

The item scaling as a vector3d type. Defaults to `vector3d(0.1, 0.1, 0.1)`.

Item scaling is specified either in data values or in absolute values, depending on the value of 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: Only absolute scaling is supported for Custom3DLabel items or for custom items used in polar graphs.

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

See also scalingAbsolute.

### scalingAbsolute : bool

Defines 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 Custom3DVolume items, the range clipping is calculated on the unrotated item.

Note: Only absolute scaling is supported for Custom3DLabel 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.

See also scaling and positionAbsolute.

### shadowCasting : bool

Defines whether shadow casting for the item is enabled. Defaults to `true`. If `false`, the item does not cast shadows regardless of ShadowQuality.

### textureFile : string

The texture file name for the item. If left 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.

### visible : bool

The visibility of the item. Defaults to `true`.

## Signal Documentation

### meshFileChanged(string meshFile)

This signal is emitted when meshFile changes to meshFile.

Note: The corresponding handler is `onMeshFileChanged`.

### positionAbsoluteChanged(bool positionAbsolute)

This signal is emitted when positionAbsolute changes to positionAbsolute.

Note: The corresponding handler is `onPositionAbsoluteChanged`.

### positionChanged(vector3d position)

This signal is emitted when item position changes to position.

Note: The corresponding handler is `onPositionChanged`.

### rotationChanged(quaternion rotation)

This signal is emitted when rotation changes to rotation.

Note: The corresponding handler is `onRotationChanged`.

### scalingAbsoluteChanged(bool scalingAbsolute)

This signal is emitted when scalingAbsolute changes to scalingAbsolute.

Note: The corresponding handler is `onScalingAbsoluteChanged`.

### scalingChanged(vector3d scaling)

This signal is emitted when scaling changes to scaling.

Note: The corresponding handler is `onScalingChanged`.

### shadowCastingChanged(bool shadowCasting)

This signal is emitted when shadowCasting changes to shadowCasting.

Note: The corresponding handler is `onShadowCastingChanged`.

### textureFileChanged(string textureFile)

This signal is emitted when textureFile changes to textureFile.

Note: The corresponding handler is `onTextureFileChanged`.

### visibleChanged(bool visible)

This signal is emitted when visible changes to visible.

Note: The corresponding handler is `onVisibleChanged`.

## Method Documentation

### void setRotationAxisAndAngle(vector3d axis, real angle)

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

See also rotation.