Custom3DItem QML Type
向图中添加一个自定义项。更多...
| Import Statement: | import QtGraphs |
| In C++: | QCustom3DItem |
| Inherited By: |
- 所有成员列表，包括继承的成员
- Custom3DItem 属于Qt Graphs 中的3D QML 类型。
属性
- meshFile : string
- position : vector3d
- positionAbsolute : bool
- rotation : quaternion
- rotationAbsolute : bool
(since 6.11) - scaling : vector3d
- scalingAbsolute : bool
- shadowCasting : bool
- textureFile : string
- visible : bool
信号
- 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)
方法
- void setRotationAxisAndAngle(vector3d axis, real angle)
详细描述
自定义项具有自定义网格、位置、缩放、旋转以及可选的纹理。
属性文档
meshFile : string
该项的网格文件名。文件中的项必须为网格格式。建议网格文件包含顶点、法线和UV坐标。
position : vector3d
项目位置以vector3d 表示。默认值为vector3d(0.0, 0.0, 0.0) 。
项目位置可通过数据坐标或绝对坐标指定，具体取决于positionAbsolute 属性的值。使用绝对坐标时，-1.0...1.0 之间的数值均在轴范围内。
注意： 若positionAbsolute 为false ，且项目 位置超出任何轴范围，则该项目 不会被渲染；除非该项目是Custom3DVolume （此时会部分可见），且scalingAbsolute 同时为false 。在这种情况下，体积的可见部分将被渲染。
另请参阅 positionAbsolute 和scalingAbsolute 。
positionAbsolute : bool
用于指定项目位置应采用数据坐标还是绝对坐标进行处理。默认值为false 。具有绝对坐标的项目将始终被渲染，而具有数据坐标的项目仅在位于轴范围之内时才会被渲染。
另请参阅 position 。
rotation : quaternion
该项的轮换方式为“quaternion ”。默认值为“quaternion(0.0, 0.0, 0.0, 0.0) ”。
rotationAbsolute : bool [since 6.11]
定义项目旋转应基于数据值还是绝对值进行处理。默认值为true 。采用绝对旋转的项目将使用默认坐标进行旋转，无论轴向如何；采用数据旋转的项目则将根据轴向坐标进行旋转。
该属性在 Qt 6.11 中引入。
另请参阅 rotation 。
scaling : vector3d
项目缩放采用vector3d 类型。默认值为vector3d(0.1, 0.1, 0.1) 。
项目缩放可通过数据值或绝对值指定，具体取决于scalingAbsolute 属性的取值。默认向量被解释为绝对值时，会将项目设置为图形高度的10%，前提是项目网格已归一化，且图形的宽高比未从默认值进行更改。
注意： 对于Custom3DLabel 项目或用于polar 图表的自定义项目，仅 支持绝对缩放。
注意：在 Qt 6.8中 ，默认会错误地将模型缩放为大小为 1（-0.5...0.5），而实际上它们被缩放为大小为 2（-1...1）。 因此，从 Qt 6.9 开始，所有自定义项的大小是 Qt 6.8 中的两倍
另请参阅 scalingAbsolute 。
scalingAbsolute : bool
定义项目缩放应基于数据值还是绝对值进行处理。默认值为true 。采用绝对缩放的项目将以相同大小渲染，无论坐标轴范围如何。 采用数据缩放的图元会根据坐标轴范围调整其显示大小。若positionAbsolute 的值为true ，则此属性将被忽略，缩放将按绝对值处理。如果图元存在旋转，则数据缩放是基于未旋转的图元计算的。同样，对于Custom3DVolume 图元，范围裁剪也是基于未旋转的图元计算的。
注意： 对于Custom3DLabel 项或用于polar 图表的自定义项，仅 支持绝对缩放。
注意： 自定义项的网格 必须归一化到[-1 ,1] 范围内，否则数据缩放将不准确。
另请参阅 scaling 和positionAbsolute 。
shadowCasting : bool
指定该项是否启用投射阴影功能。默认值为true 。如果设置为false ，则无论ShadowQuality 的值如何，该项均不会投射阴影。
textureFile : string
该物品的纹理文件名。如果未设置，将使用纯灰色纹理。
注意：为 节省内存，从文件加载的QImage 对象将在纹理创建完成后被清空。
visible : bool
该项的可见性。默认值为true 。
Signal 文档
meshFileChanged(string meshFile)
当meshFile 变为meshFile 时，会触发此信号。
注意： 相应的处理程序 是onMeshFileChanged 。
positionAbsoluteChanged(bool positionAbsolute)
当positionAbsolute 变为positionAbsolute 时，会触发此信号。
注意： 相应的处理程序 为onPositionAbsoluteChanged 。
positionChanged(vector3d position)
当项position 变为position 时，会触发此信号。
注意： 对应的处理程序 为onPositionChanged 。
rotationChanged(quaternion rotation)
当rotation 变为rotation 时，会触发此信号。
注意： 对应的处理程序 是onRotationChanged 。
scalingAbsoluteChanged(bool scalingAbsolute)
当scalingAbsolute 变为scalingAbsolute 时，会触发此信号。
注意： 相应的处理程序 是onScalingAbsoluteChanged 。
scalingChanged(vector3d scaling)
当scaling 变为scaling 时，会触发此信号。
注意： 相应的处理程序 是onScalingChanged 。
shadowCastingChanged(bool shadowCasting)
当shadowCasting 变为shadowCasting 时，会触发此信号。
注意： 相应的处理程序 是onShadowCastingChanged 。
textureFileChanged(string textureFile)
当textureFile 变为textureFile 时，会触发此信号。
注意： 相应的处理程序 是onTextureFileChanged 。
visibleChanged(bool visible)
当visible 变为visible 时，会触发此信号。
注意： 相应的处理程序 为onVisibleChanged 。
方法文档
void setRotationAxisAndAngle(vector3d axis, real angle)
一个便捷函数，用于根据axis 和angle 构建旋转四元数。
另请参阅 rotation 。
© 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.
