Qt Graphs 3D でのデータ処理

シリーズ

シリーズとは、論理的に関連付けられたデータ項目の集合と、データ項目のレンダリング方法を記述する視覚的プロパティ（項目のメッシュや色など）を組み合わせたものです。各グラフのタイプには、固有のシリーズタイプがあります。たとえば、棒グラフではQBar3DSeries が使用されます。すべてのグラフには、複数のシリーズを同時に追加することができます。各シリーズは独自のデータを保持します。

次のコードスニペットは、QBar3DSeries を使用して、棒を円柱としてレンダリングし、単色ではなくグラデーションを適用する方法を示しています：

QQuickWidget quickWidget;
Q3DBarsWidgetItem graph;
graph.setWidget(&quickWidget);

QBar3DSeries series;

QLinearGradient barGradient(0, 0, 1, 100);
barGradient.setColorAt(1.0, Qt::white);
barGradient.setColorAt(0.0, Qt::black);

series.setBaseGradient(barGradient);
series.setColorStyle(QGraphsTheme::ColorStyle::ObjectGradient);
series.setMesh(QAbstract3DSeries::Mesh::Cylinder);

graph.addSeries(&series);

データプロキシ

ユーザーが可視化したいデータはさまざまな形式で存在しますが、そのすべてを直接サポートすることはできません。 そのため、Qt Graphs ではデータプロキシが実装されており、ユーザーは既知の形式でデータをプロキシに供給できます。各グラフのシリーズには基本的なプロキシ型があり、そのグラフに適した形式でデータを受け取ります。プロキシとシリーズの関係において、データはシリーズに格納されるため、いくつかの重要な点を挙げておきます。 まず、この実装により、ユーザーはシリーズを通じてデータにアクセスできます。ユーザーがこのデータに対して追加や削除などの操作を行いたい場合でも、プロキシを通じてこれらの操作を実行できます。ただし、これらの操作を行うには、このプロキシに関連付けられたシリーズを作成する必要があります。

例えば、QBar3DSeries の基本的なプロキシはQBarDataProxy であり、これを使用してQBarDataItem オブジェクトとしてデータをシリーズに追加します。各QBarDataItem は単一のバー値を保持します。QBarDataArray およびQBarDataRow コンテナ用の追加のtypedefも提供されています。

このコードスニペットは、データが架空のmyData オブジェクトに格納されており、そのオブジェクトがQBarDataItems としてデータを返す場合の基本プロキシの使用方法を示しています：

QQuickWidget quickWidget;
Q3DBarsWidgetItem graph;
graph.setWidget(&quickWidget);

QBar3DSeries series;

for (int i = 0; i < 10; ++i) {
    QBarDataRow dataRow;
    for (int j = 0; j < 5; ++j)
        dataRow.append(myData->getValue(i, j));
    series.dataProxy()->addRow(dataRow);
}

graph.addSeries(&series);

アイテムモデルとデータマッピング

一般的なユースケースに対応するため、Qt Graphs では専用のプロキシを提供しています。その一例として、Qtアプリケーションでデータを保存する一般的な方法である、アイテムモデル（QAbstractItemModel のサブクラス）にデータを保持する場合が挙げられます。 グラフの各型には、この目的のための特別なプロキシクラスが用意されています。例えば、QBar3DSeries に対してはQItemModelBarDataProxy があります。これらのプロキシの使用方法は簡単です。データを含むアイテムモデルへのポインタを渡して、データを基本プロキシが処理できる形式にマッピングするルールを指定するだけです。

マッピングは、アイテムモデルのロールに基づいて行われます。モデル内の各データ項目は、ロールごとに異なる値を持つことができます。 たとえば、QItemModelBarDataProxy を使用すると、アイテムがどの行に属するかを決定するために使用するロール、列について同様の処理を行うロール、およびアイテムの値を指定するロールを指定できます。プロキシがモデルからデータを解決する際、これらのマッピングを使用して棒グラフの行と列を生成します。

多くの場合、アイテムモデルには、複数の値にマッピングしたい情報を含む単一のロールが存在します。これの典型的な例は、年や月といった2つの時間軸を持つ棒グラフを生成する際のタイムスタンプフィールドです。 単一のアイテムモデル・ロールを複数のデータフィールドにマッピングできるようにするため、アイテムモデル・プロキシはパターンマッチングおよび置換のメカニズムを実装する必要があります。また、このメカニズムを使用すれば、1対1のマッピングの場合であってもデータの再フォーマットを行うことができます。

グラフのタイプによっては、プロキシが他の機能もサポートする場合があります。例えば、QItemModelBarDataProxy では、QAbstractItemModel の行や列を棒グラフの行や列に直接マッピングするオプション機能などが挙げられます。

詳細および使用例については、個々のプロキシクラスを参照してください：QItemModelBarDataProxy 、QItemModelScatterDataProxy 、およびQItemModelSurfaceDataProxy 。

その他のカスタムプロキシ

QHeightMapSurfaceDataProxy は、高さマップ画像からサーフェスグラフを生成するための特殊なプロキシです。詳細については、QHeightMapSurfaceDataProxy のドキュメントを参照してください。

「Bar Graph 」タブにある「Graph Gallery」のサンプルでは、カスタムプロキシの作成方法を示しています。このサンプルでは、バリアントリストに基づいたカスタムデータセットを定義し、関連するマッパーを使用してそのデータを解決するための基本プロキシの拡張機能を実装しています。

リアルタイムデータの取り扱い

急速に更新されるデータセットを扱う場合、良好なパフォーマンスを確保するためにデータを適切に処理することが重要です。メモリの割り当ては負荷の高い操作であるため、プロキシに渡す配列を構築する際に不必要な再割り当てを避けるため、可能な限り常に `QList::reserve()` および `QList::resize()` を使用してください。

以下の必要がある場合：

• 各フレームごとにデータセット全体を変更する場合、特に配列の次元が変わらない場合は、ほとんどの場合、既存の配列を再利用するのが最善です。
• 各フレームごとに複数の行や項目を追加、挿入、削除、または変更する必要がある場合は、1行または1項目ずつ処理する複数のメソッド呼び出しを行うよりも、1回のメソッド呼び出しで行う方が常に効率的です。たとえば、10行を追加する場合、1回のQBarDataProxy::addRows()呼び出しを行う方が、QBarDataProxy::addRow()を10回個別に呼び出すよりもはるかに効率的です。

Bars3D は、データウィンドウ内のデータのみにアクセスするように最適化されているため、プロキシを使用してシリーズにデータが継続的に追加されても、目立った速度低下は生じないはずです。

スキャッターデータはソートされていないため、データウィンドウの範囲が変更されるたびに、すべてのデータポイントの可視性を確認する必要があります。これにより、プロキシにデータが継続的に追加されると、処理速度の低下が徐々に進行する可能性があります。スキャッターグラフで最高のパフォーマンスを得るには、必要なデータのみをプロキシに保持してください。

サーフェスデータは、項目レベルでは散布図データと似ていますが、すでに行と列に割り当てられています。そのため、サーフェスレンダラーは、行と列のデータがそれぞれの軸に沿ってソートされていると仮定することで、描画を最適化できます。棒グラフの場合ほど効率的ではありませんが、それに近い効率が得られます。