Back to Qt.io
Contact Us Blog Download Qt
このページでは

Surface3DNode QML Type

3Dサーフェスグラフノードの使用方法について説明します。詳細...

Import Statement: import QtGraphs
Inherits:

GraphsNode

プロパティ

信号

方法

詳細な説明

この型を使用すると、開発者は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 です。

注： Bars3D には影響しません 。

「horizontalAspectRatio」も参照してください 。

axisX : Value3DAxis

アクティブなX軸。

軸が指定されていない場合、ラベルがなく、範囲が自動的に調整される一時的なデフォルトの軸が作成されます。この一時的な軸は、別の軸が明示的に同じ向きに設定された場合に破棄されます。

axisY : Value3DAxis

アクティブなY軸。

軸が指定されていない場合、ラベルがなく、範囲が自動的に調整される一時的なデフォルトの軸が作成されます。この一時的な軸は、別の軸が同じ向きに明示的に設定されると破棄されます。

axisZ : Value3DAxis

アクティブなZ軸。

軸が指定されていない場合、ラベルがなく、範囲が自動的に調整される一時的なデフォルト軸が作成されます。この一時的な軸は、別の軸が明示的に同じ向きに設定されると破棄されます。

customItemList : list<Custom3DItem>

グラフに追加されたCustom3DItem 項目のリスト。グラフは、追加された項目の所有権を取得します。

flipHorizontalGrid : bool

用途によっては、横軸のグリッドが図の大部分を覆ってしまう場合があるため、横軸のグリッドをグラフの下部ではなく上部に表示した方が便利な場合があります。この典型的な用途として、トップダウン視点で正射影を用いた2Dスペクトログラムを表示する場合が挙げられます。

false の場合、横軸のグリッドとラベルはグラフの水平背景上に描画されます。true の場合、横軸のグリッドとラベルは、水平背景とは反対側のグラフ上に描画されます。デフォルトはfalse です。

gridLineType : Graphs3D.GridLineType

グリッド線の種類が「Graphs3D.GridLineType.Shader 」か「Graphs3D.GridLineType.Geometry 」かを指定します。

この値はすべてのグリッド線に影響します。

「Graphs3D.GridLineType」も参照してください 。

horizontalAspectRatio : real

x軸とz軸間のグラフのスケーリング比率です。0.0 の値は、軸の範囲に応じて自動的にスケーリングされることを示します。デフォルトは0.0 です。

注： このプロパティは、barThickness およびbarSpacing プロパティを介して水平方向のスケーリングを処理するBars3DNode には影響しません 。また、極座標グラフでもこのプロパティは無視されます。

関連項目： 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 です。

注：一部の環境では 、静的最適化を使用した大規模なグラフがレンダリングされない場合があります。これは、すべてのアイテムが単一のドローコールを使用してレンダリングされるためであり、グラフィックスドライバによって、1回のドローコールあたりの最大頂点数が異なるためです。この問題は主に、32ビットおよびOpenGL ES2プラットフォームで発生します。 この問題を回避するには、頂点数の少ないアイテムメッシュを選択するか、ポイントメッシュを使用してください。

関連項目： Abstract3DSeries::mesh およびGraphs3D.OptimizationHint 。

polar : bool

true の場合、横軸が極座標軸に変更されます。x軸は角度軸となり、z軸は半径軸となります。棒グラフでは極座標モードは利用できません。

デフォルトは `false` です。

「radialLabelOffset」も参照してください 。

queriedGraphPosition : vector3d [read-only]

この読み取り専用プロパティには、Scene3D::graphPositionQuery を使用してクエリされた、各軸に沿った最新のグラフ位置値が含まれます。これらの値は、[-1, 1] の範囲に正規化されています。クエリされた位置がグラフの境界外にある場合、値は実際の位置を反映せず、代わりに[-1, 1] の範囲外の未定義の位置となります。クエリが行われるまでは、この値は未定義となります。

特定の画面位置に対応する唯一の正しい3D座標は存在しないため、一貫性を保つために、クエリは常にグラフを囲む目に見えないボックスの内側を基準に行われます。

注：棒 グラフでは 、グラフの下端レベルでのみグラフ位置のクエリが可能であるため、棒グラフの y 値は常に 0 となり、有効なクエリはグラフの下端を含む画面位置でのみ実行できます。

Scene3D::graphPositionQueryも参照してください 。

radialLabelOffset : real

このプロパティは、放射状の極座標軸の軸ラベルの正規化された水平オフセットを指定します。値「0.0 」は、ラベルを角度軸の0度のグリッド線の隣に描画することを示します。値「1.0 」は、ラベルをグラフ背景の端という通常の位置に描画することを示します。このプロパティは、polarプロパティの値が「false 」の場合、無視されます。デフォルトは「1.0 」です。

polarも参照してください 。

selectedElement : Graphs3D.ElementType [read-only]

グラフで選択されている要素。

このプロパティを使用すると、選択されている要素のタイプを照会できます。このタイプは、グラフ内で新たな選択が行われ、「selectedElementChanged 」信号が発行されるまで有効です。

このシグナルは、例えば「Axis Handling」の例で示されているように、カスタマイズされた入力処理を実装するために使用できます。

selectedLabelIndex()、selectedAxis()、selectedCustomItemIndex()、selectedCustomItem()、Bars3DNode::selectedSeries 、Scatter3DNode::selectedSeries 、Scene3D::selectionQueryPosition 、およびGraphs3D.ElementTypeも参照してください 。

selectedSeries : Surface3DSeries [read-only]

選択された系列、またはnull。selectionMode にMultiSeries フラグが設定されている場合、このプロパティには、選択された点を所有する系列が格納されます。

selectionMode : Graphs3D.SelectionMode

グラフのアクティブな選択モード。graphs3d.selectionflag 列挙型の値のいずれかです。

seriesList : list<Surface3DSeries> [default]

このプロパティには、グラフのシリーズが格納されます。デフォルトでは、このプロパティには空のリストが含まれています。シリーズを設定するには、addSeries() 関数を使用するか、グラフの子要素として定義してください。

theme : GraphsTheme

グラフのアクティブなテーマ。

GraphsThemeも参照してください 。

Signal ドキュメント

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 をグラフに追加します。追加された項目の所有権はグラフが引き継ぎます。

追加に成功した場合は追加された項目のインデックスを返し、nullの項目を追加しようとした場合は-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」も参照してください 。

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