path: root/src/datavisualization/doc/src/qtdatavisualization.qdoc
diff options
authorMiikka Heikkinen <>2013-10-07 13:50:23 +0300
committerMiikka Heikkinen <>2013-10-08 09:33:35 +0300
commit79ac7ce92c9651ce420a427f786f35af97dd8491 (patch)
treeadb4d54fccef3449d92318cca32539df1e82197f /src/datavisualization/doc/src/qtdatavisualization.qdoc
parent7d9ac97c4cc8551e757dbb58b8f2bb19fbc55882 (diff)
Improve documentation on data handling
Change-Id: Ie1acb5b12eeb9b59815b7482042edc8adc0250d8 Reviewed-by: Tomi Korpipää <>
Diffstat (limited to 'src/datavisualization/doc/src/qtdatavisualization.qdoc')
1 files changed, 74 insertions, 2 deletions
diff --git a/src/datavisualization/doc/src/qtdatavisualization.qdoc b/src/datavisualization/doc/src/qtdatavisualization.qdoc
index ba158d27..7c4bcd2e 100644
--- a/src/datavisualization/doc/src/qtdatavisualization.qdoc
+++ b/src/datavisualization/doc/src/qtdatavisualization.qdoc
@@ -98,11 +98,83 @@
\section1 Data proxies
+ The data users wish to visualize comes in many formats, all of which cannot obviously be
+ directly supported. Therefore Qt Data Visualization implements data proxies into which
+ user can feed their data in a known format. Each visualization type has a basic proxy type,
+ which takes data in a format suitable for that visualization.
+ For example, the basic proxy for Q3DBars is QBarDataProxy, which stores rows of QBarDataItem
+ objects. Each QBarDataItem stores a single bar value. Additional typedefs are provided for
+ QBarDataArray and QBarDataRow containers.
+ This code snipped shows how to use basic proxy when your data is stored in some hypothetical
+ \c myData object:
+ \snippet doc_src_qtdatavisualization.cpp 10
+ \note The graph objects can own more than one data proxy, but only one proxy can be
+ active at a time. If you need to switch back and forth between two different sets of data,
+ it may be more efficient to store each set in different proxy and just change the active
+ proxy, rather than reset the data in one proxy every time you need to switch.
\section1 Item models and data mapping
+ For common use cases, Qt Data Visualization offers specialized proxies. One such case is having
+ data in an item model (QAbstractItemModel subclass), which is a common way to store data in
+ Qt applications. Each of the visualization types offers a special proxy and a corresponding mapping
+ class for this purpose, e.g. QItemModelBarDataProxy and QItemModelBarDataMapping for Q3DBars.
+ These proxies are simple to use - just give them a pointer to the item model containing the
+ data and the mapping object containing rules how to map the data into format the basic proxy can
+ digest.
+ Mapping objects work with item model roles. Each data item in the model can have different
+ values for different roles. For example, with QItemModelBarDataMapping you can specify which
+ role is used to determine which row the item belongs to, which role does the same for columns,
+ and which role specifies the value of the item. When the proxy resolves the data from the model,
+ it uses these mappings to generate the rows and columns of the bar graph.
+ Depending on the visualization type, mapping classes may support other functionality as well,
+ such as QItemModelBarDataMapping optionally mapping QAbstractItemModel rows and columns directly
+ into bar graph rows and columns. See individual mapping classes for more information and examples
+ how to use them: QItemModelBarDataMapping, QItemModelScatterDataMapping, and
+ QItemModelSurfaceDataMapping.
+ \section1 Other custom proxies
+ QHeightMapSurfaceDataProxy is a specialized proxy for generating a surface graph from a
+ heightmap image. See QHeightMapSurfaceDataProxy documentation for more information.
+ The \l{Rainfall Example}{Rainfall} example shows how a custom proxy can be created. It defines
+ a custom data set based on variant lists and an extension of the basic proxy to resolve that
+ data with an associated mapper.
+ \section1 Dealing with real-time data
+ When you have a data set that updates rapidly, it is important to handle data properly to
+ ensure good performance. Since memory allocation is a costly operation, always use
+ QList::reserve() and QVector::resize() where possible to avoid reallocations when constructing
+ the array to give to the proxy. If you need to change the entire data set for each frame,
+ it is in most cases best to re-use the existing array - especially if the array dimensions do not
+ change. If you need to add, insert, remove, or change several rows or items for each frame, it
+ is always more efficient to do it with one method call instead of multiple calls affecting
+ a single row or item each. For example, adding ten rows with a single QBarDataProxy::addRows() call
+ is much more efficient than ten separate QBarDataProxy::addRow() calls.
+ Bars renderer is optimized to access only data that is within data window and thus should not
+ suffer noticeable slowdown even if more data is continually added to the proxy.
+ Due to the unsorted nature of the scatter data, any change in the data window ranges requires
+ all data points to be checked for visibility, which can cause increasing slowdown if data is
+ continually added to the proxy.
+ Surface data, while on item level similar to scatter data, is already assigned into rows and
+ columns, so the surface renderer can do some optimization by making assumption that the data in
+ rows and columns is sorted along their respective axes, but it is nowhere near as efficient
+ as in bars case. Surface rendering can suffer significant slowdown if the data size grows unchecked.
+ For the best performance with the scatter and surface graphs, only keep the data you need in the
+ proxy.
+ \note Data handling is not yet fully optimized in the technology preview version.