このページでは

Q3DSurfaceWidgetItem Class

Q3DSurfaceWidgetItem クラスは、3D 表面プロットをレンダリングするためのメソッドを提供します。詳細...

ヘッダー: #include <Q3DSurfaceWidgetItem>
CMake: find_package(Qt6 REQUIRED COMPONENTS GraphsWidgets)
target_link_libraries(mytarget PRIVATE Qt6::GraphsWidgets)
qmake: QT += graphswidgets
継承元: Q3DGraphsWidgetItem

プロパティ

パブリック関数

Q3DSurfaceWidgetItem(QObject *parent = nullptr)
virtual ~Q3DSurfaceWidgetItem() override
void addAxis(QValue3DAxis *axis)
void addSeries(QSurface3DSeries *series)
QList<QValue3DAxis *> axes() const
QValue3DAxis *axisX() const
QValue3DAxis *axisY() const
QValue3DAxis *axisZ() const
bool flipHorizontalGrid() const
void releaseAxis(QValue3DAxis *axis)
void removeSeries(QSurface3DSeries *series)
(since 6.10) void renderSliceToImage(int index, int requestedIndex, QtGraphs3D::SliceCaptureType sliceType)
QSurface3DSeries *selectedSeries() const
QList<QSurface3DSeries *> seriesList() const

パブリックスロット

void setAxisX(QValue3DAxis *axis)
void setAxisY(QValue3DAxis *axis)
void setAxisZ(QValue3DAxis *axis)
void setFlipHorizontalGrid(bool flip)

シグナル

void axisXChanged(QValue3DAxis *axis)
void axisYChanged(QValue3DAxis *axis)
void axisZChanged(QValue3DAxis *axis)
void flipHorizontalGridChanged(bool flip)
void selectedSeriesChanged(QSurface3DSeries *series)
(since 6.10) void sliceImageChanged(const QImage &image)

詳細な説明

このクラスを使用すると、開発者は 3D サーフェスプロットをレンダリングし、シーンを自由に回転させて表示することができます。描画モードやシェーディングなど、サーフェスの視覚的なプロパティは、QSurface3DSeries を通じて制御できます。

Q3DSurfaceWidgetItem は、ユーザーがマウスの左ボタンでクリックしたデータポイント(デフォルトの入力ハンドラを使用している場合)または `QSurface3DSeries` を通じて選択されたデータポイントに、ハイライトされたボールを表示することで、選択をサポートしています。選択ポインタにはラベルが付随しており、デフォルトではデータポイントの値と座標が表示されます。

軸に表示される値の範囲およびラベルの書式は、QValue3DAxis を通じて制御できます。

グラフを回転させるには、マウスの右ボタンを押したままマウスを移動させます。ズームはマウスホイールを使用して行います。これらの操作はいずれも、デフォルトの入力ハンドラが使用されていることを前提としています。

Q3DSurfaceWidgetItemに対して軸が明示的に設定されていない場合、ラベルのない一時的なデフォルトの軸が作成されます。これらのデフォルトの軸は軸アクセサを介して変更できますが、いずれかの向きに対して軸が明示的に設定されると、その向きのデフォルトの軸は破棄されます。

最小限の Q3DSurfaceWidgetItem グラフの構築方法

まず、Q3DSurfaceWidgetItemを構築します。この例ではグラフをトップレベルウィンドウとして実行するため、デフォルトで設定されているQt::FramelessWindowHint フラグをクリアする必要があります:

QQuickWidget quickWidget;
Q3DSurfaceWidgetItem surface;
surface.setWidget(&quickWidget);
surface.widget()->setMinimumSize(QSize(256, 256));

これで、Q3DSurfaceWidgetItemはレンダリング対象のデータを受け入れる準備が整いました。値を受け取るためのデータ要素を作成します:

注: 新しいプロキシ・シリーズ関係では 、データはシリーズ内に保持されます。したがって、プロキシがデータの追加、削除、編集を行えるようにするには、まずシリーズを作成することが前提条件となります。

まず、データを行要素に読み込み、そのポインタをデータ要素に追加します:

dataRow1 << QSurfaceDataItem(0.0f, 0.1f, 0.5f) << QSurfaceDataItem(1.0f, 0.5f, 0.5f);
dataRow2 << QSurfaceDataItem(0.0f, 1.8f, 1.0f) << QSurfaceDataItem(1.0f, 1.2f, 1.0f);
data << dataRow1 << dataRow2;

新しいシリーズを作成し、データを設定します:

QSurface3DSeries series;
series.dataProxy()->resetArray(data);
surface.addSeries(&series);

最後に、表示するように設定する必要があります:

surface.widget()->show();

このグラフを作成して表示するために必要な完全なコードは次のとおりです:

#include <QtGraphs>
#include <QtGraphsWidgets/q3dsurfacewidgetitem.h>
#include <QtWidgets/qapplication.h>

int main(int argc, char **argv)
{
    QApplication app(argc, argv);

    QQuickWidget quickWidget;
    Q3DSurfaceWidgetItem surface;
    surface.setWidget(&quickWidget);
    surface.widget()->setMinimumSize(QSize(256, 256));
    QSurfaceDataArray data;
    QSurfaceDataRow dataRow1;
    QSurfaceDataRow dataRow2;

    dataRow1 << QSurfaceDataItem(0.0f, 0.1f, 0.5f) << QSurfaceDataItem(1.0f, 0.5f, 0.5f);
    dataRow2 << QSurfaceDataItem(0.0f, 1.8f, 1.0f) << QSurfaceDataItem(1.0f, 1.2f, 1.0f);
    data << dataRow1 << dataRow2;

    QSurface3DSeries series;
    series.dataProxy()->resetArray(data);
    surface.addSeries(&series);
    surface.widget()->show();

    return app.exec();
}

そして、この数行のコードによって次のような結果が得られます:

傾斜した緑色の平面を含む3D表面プロット

シーンの回転やズームインが可能で、サーフェスの点を選択してその位置を確認することもできますが、この最小限のコード例にはそれ以外のインタラクションは含まれていません。詳細については、「Surface Graph Gallery」などの提供されている例を参照して理解を深めてください。

関連項目: Q3DBarsWidgetItem 、Q3DScatterWidgetItem 、およびQt Graphs C++ Classes for 3D。

プロパティのドキュメント

axisX : QValue3DAxis*

このプロパティは、アクティブな x 軸を保持します。

axis をアクティブなX軸として設定します。暗黙的にaddAxis()を呼び出し、軸の所有権をこのグラフに移します。

axis が null の場合、ラベルがなく、範囲が自動的に調整される一時的なデフォルトの軸が作成されます。

別の軸が明示的に同じ向きに設定された場合、この一時的な軸は破棄されます。

アクセス関数:

QValue3DAxis *axisX() const
void setAxisX(QValue3DAxis *axis)

通知シグナル:

void axisXChanged(QValue3DAxis *axis)

addAxis() およびreleaseAxis()も参照してください 。

axisY : QValue3DAxis*

このプロパティは、アクティブなY軸を保持します。

axis をアクティブなy軸として設定します。暗黙的にaddAxis()を呼び出し、軸の所有権をこのグラフに移譲します。

axis が null の場合、ラベルがなく、範囲が自動的に調整される一時的なデフォルトの軸が作成されます。

別の軸が明示的に同じ向きに設定された場合、この一時的な軸は破棄されます。

アクセス関数:

QValue3DAxis *axisY() const
void setAxisY(QValue3DAxis *axis)

通知シグナル:

void axisYChanged(QValue3DAxis *axis)

addAxis() およびreleaseAxis()も参照してください 。

axisZ : QValue3DAxis*

このプロパティは、アクティブなZ軸を保持します。

axis をアクティブなZ軸として設定します。暗黙的にaddAxis()を呼び出し、軸の所有権をこのグラフに移します。

axis が null の場合、ラベルがなく、範囲が自動的に調整される一時的なデフォルトの軸が作成されます。

別の軸が明示的に同じ向きに設定された場合、この一時的な軸は破棄されます。

アクセス関数:

QValue3DAxis *axisZ() const
void setAxisZ(QValue3DAxis *axis)

通知シグナル:

void axisZChanged(QValue3DAxis *axis)

addAxis() およびreleaseAxis()も参照してください 。

flipHorizontalGrid : bool

このプロパティは、横軸の目盛りがグラフの下部ではなく上部に表示されるかどうかを指定します。

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

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

アクセス関数:

bool flipHorizontalGrid() const
void setFlipHorizontalGrid(bool flip)

通知シグナル:

void flipHorizontalGridChanged(bool flip)

[read-only] selectedSeries : QSurface3DSeries*

このプロパティには、選択されたシリーズ、またはnullが格納されます。

selectionModeにMultiSeries が設定されている場合、このプロパティには、選択された点を所有するシリーズが格納されます。

アクセス関数:

QSurface3DSeries *selectedSeries() const

通知シグナル:

void selectedSeriesChanged(QSurface3DSeries *series)

メンバー関数のドキュメント

[explicit] Q3DSurfaceWidgetItem::Q3DSurfaceWidgetItem(QObject *parent = nullptr)

オプションのparent を使用して、新しい3Dサーフェスグラフを作成します。

[override virtual noexcept] Q3DSurfaceWidgetItem::~Q3DSurfaceWidgetItem()

3Dサーフェスグラフを削除します。

void Q3DSurfaceWidgetItem::addAxis(QValue3DAxis *axis)

axis をグラフに追加します。addAxis を通じて追加された軸はまだ使用されるわけではありません。addAxis は、単にaxis の所有権をグラフに割り当てるために使用されます。axis は null であるか、別のグラフに追加済みであってはなりません。

releaseAxis()、setAxisX()、setAxisY()、およびsetAxisZ()も参照してください 。

void Q3DSurfaceWidgetItem::addSeries(QSurface3DSeries *series)

series をグラフに追加します。グラフには複数の系列を含めることができますが、軸のセットは1つだけです。新しく追加された系列に選択項目が指定されている場合、その項目が強調表示され、既存の選択は解除されます。アクティブな選択が有効なのは、追加された系列のうち1つだけです。

「Q3DGraphsWidgetItem::hasSeries()」も参照してください 。

QList<QValue3DAxis *> Q3DSurfaceWidgetItem::axes() const

追加されたすべての軸のリストを返します。

addAxis()も参照してください 。

void Q3DSurfaceWidgetItem::releaseAxis(QValue3DAxis *axis)

axis が本グラフに追加されている場合、その所有権を呼び出し元に返します。解放されたaxis が使用中の場合、新しいデフォルト軸が作成され、アクティブに設定されます。

デフォルト軸が解放され、後で再び追加された場合、その挙動は他の軸と同様に動作します。

addAxis()、setAxisX()、setAxisY()、およびsetAxisZ()も参照してください 。

void Q3DSurfaceWidgetItem::removeSeries(QSurface3DSeries *series)

グラフからseries を削除します。

Q3DGraphsWidgetItem::hasSeries()も参照してください 。

[since 6.10] void Q3DSurfaceWidgetItem::renderSliceToImage(int index, int requestedIndex, QtGraphs3D::SliceCaptureType sliceType)

指定されたスライスビューを画像としてエクスポートします。スライス結果は、index の一連のデータとなります。すべてのシリーズをエクスポートするには、index を-1に設定してください。エクスポートされるスライスは、sliceType で定義される行または列の1行であり、指定されたrequestedIndex の位置にあります。

sliceImageChanged シグナルは、画像の準備が整ったときに発せられ、次のように捕捉できます:

connect(item, &Q3DSurfaceWidgetItem::sliceImageChanged, this, [](const QImage &image) {
    // ~~~
});

item->renderSliceToImage(sliceType, index);

画像は、現在のアンチエイリアシング設定でレンダリングされます。

この関数は Qt 6.10 で導入されました。

QQuickItem::grabToImage() およびsliceImageChanged()も参照してください 。

QList<QSurface3DSeries *> Q3DSurfaceWidgetItem::seriesList() const

このグラフに追加された系列のリストを返します。

Q3DGraphsWidgetItem::hasSeries()も参照してください 。

[signal, since 6.10] void Q3DSurfaceWidgetItem::sliceImageChanged(const QImage &image)

renderSliceToImage がimage の準備を完了したときに発せられます。

この関数は Qt 6.10 で導入されました。

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