Surface3DNode QML Type

描述了 3D 曲面图节点的使用方法。更多内容...

• 所有成员列表，包括继承的成员
• Surface3DNode 属于Qt Graphs 的3D QML 类型。

属性

• 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 将曲面图节点以3D形式渲染出来。

要使用此类型，您需要导入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 中的3D相关C++类。

属性文档

aspectRatio : real

图表中水平平面上的最长轴与y轴之间的缩放比例。默认值为2.0 。

另请参阅 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 。

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

labelMargin : real

此属性用于指定坐标轴标签的放置间距。

负值将标签放置在绘图区域内部，而正值将标签放置在绘图区域外部。当该值为负时，标签的自动旋转功能将被禁用。默认值为0.1

另请参阅 QAbstract3DAxis::labelAutoAngle 。

locale : locale

设置用于格式化各种数值标签的区域设置。默认使用"C" 区域设置。

另请参阅 Value3DAxis::labelFormat 。

margin : real

用于确定可绘制图表区域边缘与图表背景边缘之间留白距离的绝对值。

如果边距值为负数，则边距将自动确定，并可能根据数据系列中数据点的大小和图表类型而有所不同。如果图表的宽高比未从默认值进行更改，则该值将被解释为 y 轴范围的百分比。默认值为-1.0 。

optimizationHint : Graphs3D.OptimizationHint

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

默认模式采用实例化渲染，在大多数系统上能以最佳性能提供完整的功能集。静态模式可优化图渲染，非常适合大型且数据不变的数据集。但在数据动态变化和项目旋转时，其渲染速度会变慢。 选择操作未经过优化，因此不建议在海量数据集上使用静态模式。旧版模式会单独渲染图中的所有项，而不进行实例化。仅当默认模式无法正常工作时才应使用该模式，即目标系统不支持实例化时。默认值为Default 。

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

polar : bool

如果设置为true ，则横坐标轴将变为极坐标轴。x 轴变为角坐标轴，z 轴变为半径坐标轴。条形图不支持极坐标模式。

默认值为false 。

另请参阅 radialLabelOffset 。

queriedGraphPosition : vector3d [read-only]

此只读属性包含通过 `Scene3D::graphPositionQuery` 查询得到的、沿各轴的最新图表位置值。这些值已归一化至范围[-1, 1] 。如果查询的位置超出图表边界，则这些值不会反映实际位置，而是会显示为范围[-1, 1] 之外的某个未定义位置。在进行查询之前，该值将保持未定义状态。

由于不存在与特定屏幕位置完全对应的唯一正确 3D 坐标，因此为了保持一致性，查询始终针对包围图表的不可见矩形框的内侧进行。

另请参阅 Scene3D::graphPositionQuery 。

radialLabelOffset : real

该属性指定径向极坐标轴上轴标注的归一化水平偏移量。值0.0 表示应将轴标注绘制在0角度的角轴网格线旁。值1.0 表示轴标注绘制在图表背景边缘的常规位置。如果polar属性的值为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 。

Signal 文档

axisXChanged(ValueAxis3D axis)

当axisX 变为axis 时，会发出此信号。

axisYChanged(ValueAxis3D axis)

当axisY 变为axis 时，会触发此信号。

axisZChanged(ValueAxis3D axis)

当axisZ 变为axis 时，会触发此信号。

flipHorizontalGridChanged(bool flip)

当flipHorizontalGrid 变为flip 时，会触发此信号。

selectedSeriesChanged(Surface3DSeries series)

当selectedSeries 变为series 时，会触发此信号。

方法文档

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)

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

void removeCustomItemAt(vector3d position)

删除position 下的所有自定义项目。并释放分配给这些项目的资源。

void removeCustomItems()

删除所有自定义项目。并释放分配给这些项目的资源。

void removeSeries(Surface3DSeries series)

从图中移除series 。

另请参阅 GraphsNode::hasSeries()。

Abstract3DAxis selectedAxis()

可用于在接收到selectedElementChanged 信号后获取所选轴，该信号的标签类型不限。该选择在收到下一个selectedElementChanged 信号之前一直有效。

返回所选轴，或返回 null。

另请参阅 selectedElement 。

Custom3DItem selectedCustomItem()

可在接收到类型为ElementType.CustomItem 的selectedElementChanged 信号后，用于获取所选的自定义项。该项的所有权仍归图所有。选中状态在收到下一个selectedElementChanged 信号之前一直有效。

返回所选的自定义项，或 null。

另请参阅 selectedElement 。

qsizetype selectedCustomItemIndex()

可在接收到类型为ElementType.CustomItem 的selectedElementChanged 信号后，用于查询所选自定义项的索引。该选择在收到下一个selectedElementChanged 信号之前一直有效。

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

另请参阅 selectedElement 。

int selectedLabelIndex()

可在接收到selectedElementChanged 信号后，用于查询所选标签的索引，支持任何标签类型。该选择在收到下一个selectedElementChanged 信号之前一直有效。

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

另请参阅 selectedElement 。