Surface3DNode QML Type

描述三维曲面图节点的用法。更多

Import Statement:	`import QtGraphs`
Inherits:	GraphsNode

所有成员（包括继承成员）列表
Surface3DNode 是Qt Graphs QML Types for 3D 的一部分。

属性

aspectRatio : real
axisX : Value3DAxis
axisY : Value3DAxis
axisZ : Value3DAxis
customItemList : list<Custom3DItem>
flipHorizontalGrid : bool
gridLineType : Graphs3D.GridLineType
horizontalAspectRatio : real
labelMargin : real
locale : locale
margin : real
optimizationHint : Graphs3D.OptimizationHint
polar : bool
queriedGraphPosition : vector3d
radialLabelOffset : real
selectedElement : Graphs3D.ElementType
selectedSeries : Surface3DSeries
selectionMode : Graphs3D.SelectionMode
seriesList : list<Surface3DSeries>
theme : GraphsTheme

信号

axisXChanged(ValueAxis3D axis)
axisYChanged(ValueAxis3D axis)
axisZChanged(ValueAxis3D axis)
flipHorizontalGridChanged(bool flip)
selectedSeriesChanged(Surface3DSeries series)

方法

qsizetype addCustomItem(Custom3DItem item)
void addSeries(Surface3DSeries series)
void clearSelection()
void doPicking(QPoint point)
void doRayPicking(QVector3D origin, QVector3D direction)
bool hasSeries(Abstract3DSeries series)
void releaseCustomItem(Custom3DItem item)
void removeCustomItem(Custom3DItem item)
void removeCustomItemAt(vector3d position)
void removeCustomItems()
void removeSeries(Surface3DSeries series)
Abstract3DAxis selectedAxis()
Custom3DItem selectedCustomItem()
qsizetype selectedCustomItemIndex()
int selectedLabelIndex()

详细说明

开发人员可以使用该类型通过Qt Quick 渲染三维曲面图节点。

您需要导入Qt Graphs 模块才能使用该类型：

import QtGraphs

之后，您就可以在 qml 文件中使用 Surface3DNode 了：

import QtQuick
import QtGraphs

View3D {
    width: 640
    height: 480

    Surface3DNode {
        width: parent.width
        height: parent.height
        Surface3DSeries {
            itemLabelFormat: "Pop density at (@xLabel N, @zLabel E): @yLabel"
            ItemModelSurfaceDataProxy {
                itemModel: dataModel
                // Mapping model roles to surface series rows, columns, and values.
                rowRole: "longitude"
                columnRole: "latitude"
                yPosRole: "pop_density"
            }
        }

        onTapped: {
            // Disable the default input handler
            unsetDefaultTapHandler()
            // Implement own custom event handler
            console.log("Custom tap event handler")
        }
    }
    ListModel {
        id: dataModel
        ListElement{ longitude: "20"; latitude: "10"; pop_density: "4.75"; }
        ListElement{ longitude: "21"; latitude: "10"; pop_density: "3.00"; }
        ListElement{ longitude: "22"; latitude: "10"; pop_density: "1.24"; }
        ListElement{ longitude: "23"; latitude: "10"; pop_density: "2.53"; }
        ListElement{ longitude: "20"; latitude: "11"; pop_density: "2.55"; }
        ListElement{ longitude: "21"; latitude: "11"; pop_density: "2.03"; }
        ListElement{ longitude: "22"; latitude: "11"; pop_density: "3.46"; }
        ListElement{ longitude: "23"; latitude: "11"; pop_density: "5.12"; }
        ListElement{ longitude: "20"; latitude: "12"; pop_density: "1.37"; }
        ListElement{ longitude: "21"; latitude: "12"; pop_density: "2.98"; }
        ListElement{ longitude: "22"; latitude: "12"; pop_density: "3.33"; }
        ListElement{ longitude: "23"; latitude: "12"; pop_density: "3.23"; }
        ListElement{ longitude: "20"; latitude: "13"; pop_density: "4.34"; }
        ListElement{ longitude: "21"; latitude: "13"; pop_density: "3.54"; }
        ListElement{ longitude: "22"; latitude: "13"; pop_density: "1.65"; }
        ListElement{ longitude: "23"; latitude: "13"; pop_density: "2.67"; }
    }
}

另请参阅 Surface3DSeries,ItemModelSurfaceDataProxy,Bars3DNode,Scatter3DNode 和Qt Graphs C++ 3D 类。

属性文档

aspectRatio : real

水平面最长轴与 Y 轴之间的图形缩放比例。默认为2.0 。

注：对Bars3D 没有影响。

另请参阅 horizontalAspectRatio 。

axisX : Value3DAxis

活动 x 轴。

如果没有给出坐标轴，则会创建一个没有标签和自动调整范围的临时默认坐标轴。如果明确将另一个轴设置为相同方向，则会销毁该临时轴。

axisY : Value3DAxis

活动 Y 轴。

如果没有给出轴，则会创建一个没有标签和自动调整范围的临时默认轴。如果另一个轴被明确设置为相同方向，则该临时轴将被销毁。

axisZ : Value3DAxis

活动 Z 轴。

如果没有给出轴，则会创建一个没有标签和自动调整范围的临时默认轴。如果另一个轴被明确设置为相同方向，该临时轴将被销毁。

customItemList : list<Custom3DItem>

添加到图形中的Custom3DItem 项目列表。图形拥有已添加项的所有权。

flipHorizontalGrid : bool

在某些使用案例中，横轴网格大部分被表面覆盖，因此将横轴网格显示在图形顶部比显示在底部更有用。一个典型的使用案例就是使用正投影图形以自上而下的视角显示二维频谱图。

如果false ，横轴网格和标签将绘制在图表的水平背景上。如果为true ，则横轴网格和标签绘制在图形与水平背景相反的一侧。默认为false 。

gridLineType : Graphs3D.GridLineType

定义网格线类型是Graphs3D.GridLineType.Shader 还是Graphs3D.GridLineType.Geometry 。

该值会影响所有网格线。

另请参阅 Graphs3D.GridLineType 。

horizontalAspectRatio : real

x 轴和 z 轴之间的图形缩放比例。0.0 表示根据坐标轴范围自动缩放。默认值为0.0 。

注：对Bars3DNode 没有影响，它通过barThickness 和barSpacing 属性处理水平面的缩放。极坐标图也忽略此属性。

另请参阅 aspectRatio,polar,Bars3DNode::barThickness, 和Bars3DNode::barSpacing 。

labelMargin : real

该属性指定了轴标签放置的边距。

负值用于将标签置于绘图区域内，正值用于将标签置于绘图区域外。当值为负数时，将禁用标签自动旋转功能。默认值为0.1

另请参阅 QAbstract3DAxis::labelAutoAngle 。

locale : locale

设置用于格式化各种数字标签的本地语言。默认为"C" locale。

另请参阅 Value3DAxis::labelFormat 。

margin : real

可绘图区域边缘与图形背景边缘之间留出空间的绝对值。

如果边距值为负数，边距将自动确定，并根据系列中项目的大小和图形类型而变化。如果图形纵横比未从默认值中更改，则该值将被解释为 Y 轴范围的一部分。默认值为-1.0 。

注意： 如果为散点图设置的边距小于自动确定的边距，可能会导致图形边缘的散点项与图形背景重叠。

注：在散点图和曲面图中，如果边距小于坐标轴标签尺寸，则会调整坐标轴边缘标签的位置，以避免与相邻坐标轴的边缘标签重叠。

optimizationHint : Graphs3D.OptimizationHint

指定使用默认模式还是传统模式进行渲染优化。

默认模式使用实例渲染，可在大多数系统上以最佳性能提供完整的功能集。静态模式可优化图形渲染，是大型非变化数据集的理想选择。但在动态数据变化和项目旋转的情况下，该模式的运行速度较慢。选择模式未进行优化，因此不建议在海量数据集上使用静态模式。传统模式会单独渲染图形中的所有项目，而不会实例化。只有在默认模式不工作时，即目标系统不支持实例化时，才应使用该模式。默认值为Default 。

注意： 在某些环境下，使用静态优化的大型图形可能无法渲染，因为所有项目都是通过单次绘制调用渲染的，而不同的图形驱动程序支持不同的每次调用最大顶点数。这个问题主要出现在 32 位和 OpenGL ES2 平台上。要解决这个问题，可以选择顶点数较少的项目网格或使用点网格。

另请参见 Abstract3DSeries::mesh 和Graphs3D.OptimizationHint 。

polar : bool

如果true ，水平轴将变为极坐标轴。x 轴变为角度轴，z 轴变为径向轴。极轴模式不适用于条形图。

默认为false 。

另请参阅 radialLabelOffset 。

queriedGraphPosition : vector3d [read-only]

此只读属性包含使用Scene3D::graphPositionQuery 查询到的沿各轴的最新图形位置值。这些值已归一化，范围为[-1, 1] 。如果查询到的位置超出了图形边界，则该值将不会反映真实位置，而是[-1, 1] 范围外的某个未定义位置。在进行查询之前，该值都是未定义的。

没有一个正确的三维坐标与特定的屏幕位置相匹配，因此为了保持一致，查询总是针对图形周围的一个不可见方框的内侧进行。

注意： 条形图只允许在图形底层查询图形位置，因此条形图的 y 值始终为零，只能在包含图形底层的屏幕位置进行有效查询。

另请参阅 Scene3D::graphPositionQuery 。

radialLabelOffset : real

该属性指定径向极轴标签的归一化水平偏移。0.0 表示标签应绘制在 0 角度角轴网格线旁边。1.0 表示标签绘制在图形背景边缘的常规位置。如果极坐标属性值为false ，该属性将被忽略。默认值为1.0 。

另请参阅 polar 。

selectedElement : Graphs3D.ElementType [read-only]

图形中选择的元素。

该属性可用于查询所选元素的类型。该类型一直有效，直到在图形中做出新的选择并发出selectedElementChanged 信号。

例如，该信号可用于实现自定义输入处理，如轴线处理示例所示。

另请参阅 selectedLabelIndex(),selectedAxis(),selectedCustomItemIndex(),selectedCustomItem(),Bars3DNode::selectedSeries,Scatter3DNode::selectedSeries,Scene3D::selectionQueryPosition, 和Graphs3D.ElementType 。

selectedSeries : Surface3DSeries [read-only]

所选系列或为空。如果selectionMode 设置了MultiSeries 标志，则该属性将保留拥有所选点的序列。

selectionMode : Graphs3D.SelectionMode

图形中的活动选择模式。graphs3d.selectionflag 枚举值之一。

seriesList : list<Surface3DSeries> [default]

该属性用于保存图形的系列。默认情况下，该属性包含一个空列表。要设置序列，可使用addSeries() 函数或将其定义为图形的子序列。

theme : GraphsTheme

图表的活动主题。

另请参见 GraphsTheme 。

信号文档

axisXChanged(ValueAxis3D axis)

当axisX 更改为axis 时，将发出该信号。

注：相应的处理程序是onAxisXChanged 。

axisYChanged(ValueAxis3D axis)

当axisY 变更为axis 时发出此信号。

注：相应的处理程序是onAxisYChanged 。

axisZChanged(ValueAxis3D axis)

当axisZ 变更为axis 时，发出该信号。

注：相应的处理程序是onAxisZChanged 。

flipHorizontalGridChanged(bool flip)

当flipHorizontalGrid 变更为flip 时，发出此信号。

注：相应的处理程序是onFlipHorizontalGridChanged 。

selectedSeriesChanged(Surface3DSeries series)

当selectedSeries 变更为series 时，发出此信号。

注：相应的处理程序是onSelectedSeriesChanged 。

方法文档

qsizetype addCustomItem(Custom3DItem item)

将Custom3DItem item 添加到图。图形拥有添加项的所有权。

如果添加成功，则返回已添加项的索引；如果试图添加一个空项，则返回-1；如果试图添加一个已添加项，则返回该项的索引。

另请参阅 removeCustomItems()、removeCustomItem() 和removeCustomItemAt()。

void addSeries(Surface3DSeries series)

将series 添加到图形中。

另请参阅 GraphsNode::hasSeries()。

void clearSelection()

清除所有附加系列的选择。

void doPicking(QPoint point)

使用point 中的视图坐标对图形元素执行拾取，选择第一个命中的项目。默认输入处理会在接收到 onTapped 事件时执行此操作。

另请参阅 selectedElement 。

void doRayPicking(QVector3D origin, QVector3D direction)

从origin 开始，在direction 中对图形元素执行拾取，选择第一个命中的项目。

另请参阅 selectedElement 。

bool hasSeries(Abstract3DSeries series)

返回series 是否已添加到图形中。

void releaseCustomItem(Custom3DItem item)

取回item 的所有权并从图中删除item 。

注意： 如果同一项目再次添加到图形中，则需要重新设置纹理文件。

另请参阅 Custom3DItem::textureFile 。

void removeCustomItem(Custom3DItem项目）

删除自定义item 。删除分配给它的资源。

void removeCustomItemAt(vector3d position)

删除position 上的所有自定义项目。删除为其分配的资源。

void removeCustomItems()

删除所有自定义项目。删除为其分配的资源。

void removeSeries(Surface3DSeries series)

从图形中删除series 。

另请参阅 GraphsNode::hasSeries() 。

Abstract3DAxis selectedAxis()

在收到selectedElementChanged 信号后，可使用任何标签类型获取所选坐标轴。选择有效期至下一个selectedElementChanged 信号发出。

返回选中的轴或空值。

另请参阅 selectedElement 。

Custom3DItem selectedCustomItem()

在收到selectedElementChanged 信号后，可使用ElementType.CustomItem 类型获取选定的自定义项。项目的所有权仍归图形所有。在下一个selectedElementChanged 信号发出之前，选择有效。

返回选中的自定义项目或 null。

另请参阅 selectedElement 。

qsizetype selectedCustomItemIndex()

在收到selectedElementChanged 信号（类型为ElementType.CustomItem ）后，可用于查询所选自定义项的索引。选择有效期至下一个selectedElementChanged 信号发出为止。

返回所选自定义项的索引或-1。

另请参阅 selectedElement 。

int selectedLabelIndex()

在收到selectedElementChanged 信号后，可使用任何标签类型查询所选标签的索引。选择在下一个selectedElementChanged 信号发出前有效。

返回所选标签的索引或-1。

另请参阅 selectedElement 。

© 2025 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.