summaryrefslogtreecommitdiffstats
path: root/src
diff options
context:
space:
mode:
authorLeena Miettinen <riitta-leena.miettinen@qt.io>2017-03-15 16:30:41 +0100
committerLeena Miettinen <riitta-leena.miettinen@qt.io>2017-03-21 12:06:57 +0000
commit349fe9e201c16d1bc0a96ef7359866bd7430f96b (patch)
tree34b8a29cde8f1a328fba31696b039503b9126cf5 /src
parentfb9e66188e0582a6b80ad3b8b3ac80024180a9df (diff)
Doc: Add an overview of data visualization
Move some information from the front page and the known issues to the overview. Add some information to the interacting with data topic. Change-Id: Ia63e1d46ec48861a144c51f0d8796809ea771ea4 Reviewed-by: Tomi Korpipää <tomi.korpipaa@qt.io>
Diffstat (limited to 'src')
-rw-r--r--src/datavisualization/doc/src/qtdatavisualization-index.qdoc34
-rw-r--r--src/datavisualization/doc/src/qtdatavisualization-overview.qdoc250
-rw-r--r--src/datavisualization/doc/src/qtdatavisualization.qdoc30
3 files changed, 279 insertions, 35 deletions
diff --git a/src/datavisualization/doc/src/qtdatavisualization-index.qdoc b/src/datavisualization/doc/src/qtdatavisualization-index.qdoc
index 10534df3..fc09b08e 100644
--- a/src/datavisualization/doc/src/qtdatavisualization-index.qdoc
+++ b/src/datavisualization/doc/src/qtdatavisualization-index.qdoc
@@ -32,29 +32,15 @@
\page qtdatavisualization-index.html
\brief Provides functionality for 3D visualization.
- Qt Data Visualization module provides a way to visualize data in 3D.
- \section1 Features
+ Qt Data Visualization module provides a way to visualize data in 3D as bar,
+ scatter, and surface graphs. It is especially useful for visualizing depth
+ maps and large quantities of rapidly changing data, such as data received
+ from multiple sensors. The look and feel of graphs can be customized
+ by using themes or by adding custom items and labels to them.
- \list
- \li Multiple data visualization options: 3D Bars, 3D Scatter, and 3D Surface
- \li 2D slice views of the 3D data
- \li Interactive data: rotate, zoom, and highlight data using mouse or touch
- \li Uses OpenGL for rendering the data
- \li QML2 support
- \li Customizable axes for data
- \list
- \li Control viewable data window with axis ranges
- \li Customize value axis grid lines and labels with axis formatters
- \li Polar horizontal axes support for surface and scatter graphs
- \endlist
- \li Customizable input handling
- \li Customizable themes
- \li Custom items and labels can be added to any graph
- \li Ready-made data proxies to visualize data from Qt item models and height maps
- \li Perspective and orthographic projections
- \li Volumetric custom items
- \endlist
+ Qt Data Visualization is built on Qt 5 and OpenGL to take advantage of
+ hardware acceleration and Qt Quick 2.
\section1 Getting Started
@@ -75,13 +61,9 @@
\snippet doc_src_qtdatavisualization.pro 0
- For more information about creating applications that contain different
- types of graphs, see \l{How to construct a minimal Q3DBars graph},
- \l{How to construct a minimal Q3DScatter graph}, or
- \l{How to construct a minimal Q3DSurface graph}.
-
\section1 Articles
\list
+ \li \l{Qt Data Visualization Overview}{Overview}
\li \l{Qt Data Visualization Data Handling}{Data Handling}
\li \l{Qt Data Visualization Interacting with Data}{Interacting with Data}
\li \l{Qt Data Visualization Known Issues}{Known Issues}
diff --git a/src/datavisualization/doc/src/qtdatavisualization-overview.qdoc b/src/datavisualization/doc/src/qtdatavisualization-overview.qdoc
new file mode 100644
index 00000000..8cb656b1
--- /dev/null
+++ b/src/datavisualization/doc/src/qtdatavisualization-overview.qdoc
@@ -0,0 +1,250 @@
+/****************************************************************************
+**
+** Copyright (C) 2017 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the Qt Data Visualization module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:GPL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3 or (at your option) any later version
+** approved by the KDE Free Qt Foundation. The licenses are as published by
+** the Free Software Foundation and appearing in the file LICENSE.GPL3
+** included in the packaging of this file. Please review the following
+** information to ensure the GNU General Public License requirements will
+** be met: https://www.gnu.org/licenses/gpl-3.0.html.
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \title Qt Data Visualization Overview
+ \page qtdatavisualization-overview.html
+ \brief An overview of the Qt Data Visualization module.
+
+ The Qt Data Visualization module provides a way to develop rapidly
+ responding, complex, and dynamic 3D visualization for analytical demanding
+ industries such as academic research and medical. Qt 3D Data Visualization
+ provides 3D bars, scatter, and surface visualizations. Combining user
+ interaction and real time 3D drawing visualizations enables creating user
+ interfaces that use space effectively. Changing between 3D and 2D
+ presentation enables truly utilizing the value of 3D in visualizing data.
+
+ The look and feel of the graphs can be customized by using the predefined
+ themes or defining new ones. In addition, scenes can be customized by
+ specifying settings for the camera, and individual items can be customized
+ by using predefined or user-defined meshes.
+
+ Qt Data Visualization offers ready-made data proxies that can be used to
+ visualize data from Qt item models and height maps. Each graph type has a
+ basic proxy type, which accepts data in a format suitable for that
+ visualization. For more information, see \l{Qt Data Visualization Data
+ Handling}.
+
+ End users can interact with the data presented by graphs in several ways,
+ including rotating graphs, zooming into and out of data, selecting items,
+ and viewing 2D slices of the 3D data for increased readability. For more
+ information, see \l{Qt Data Visualization Interacting with Data}.
+
+ \section1 Graph Types
+
+ The Qt Data Visualization module provides the following 3D graph types:
+
+ \list
+ \li \l{3D Bar Graphs}{3D bar graphs}
+ \li \l{3D Scatter Graphs}{3D scatter graphs}
+ \li \l{3D Surface Graphs}{3D surface graphs}
+ \endlist
+
+ The QAbstract3DGraph class subclasses a QWindow and provides a render loop
+ for its own subclasses that implement the different graph types: Q3DBars,
+ Q3DScatter, and Q3DSurface. The graph type determines how the data is
+ presented.
+
+ \section2 3D Bar Graphs
+
+ 3D bar graphs present data as 3D bars that are grouped by category. The
+ Q3DBars class is used to create a graph and the QBar3DSeries and
+ QBarDataProxy classes are used to set data to the graph, as well as to
+ control the visual properties of the graph, such as draw mode and shading.
+ In QML, the corresponding types are Bars3D, Bar3DSeries, and BarDataProxy.
+
+ \image q3dbars-minimal.png
+
+ For more information, see \l{How to construct a minimal Q3DBars graph},
+ \l {Bars Example}, and \l {Qt Quick 2 Bars Example}.
+
+ \section2 3D Scatter Graphs
+
+ 3D scatter graphs present data as a collection of points. The Q3DScatter
+ class is used to create a graph and the QScatter3DSeries and
+ QScatterDataProxy classes are used to set data to the graph, as well as to
+ control the visual properties of the graph. In QML, the corresponding types
+ are Scatter3D, Scatter3DSeries, and ScatterDataProxy.
+
+ \image q3dscatter-minimal.png
+
+ For more information, see \l{How to construct a minimal Q3DScatter graph},
+ \l{Scatter Example}, and \l{Qt Quick 2 Scatter Example}.
+
+ \section2 3D Surface Graphs
+
+ 3D surface graphs present data as 3D surface plots. The Q3DSurface class is
+ used to create a graph and the QSurface3DSeries and QSurfaceDataProxy
+ classes are used to set data to the graph, as well as to control the visual
+ properties of the graph. In QML, the corresponding types are Surface3D,
+ Surface3DSeries, and SurfaceDataProxy.
+
+ \image q3dsurface-minimal.png
+
+ For more information, see \l{How to construct a minimal Q3DSurface graph},
+ \l{Surface Example}, \l{Textured Surface Example}, \l{Qt Quick 2 Surface
+ Example}, and \l{Qt Quick 2 Surface Multiseries Example}.
+
+ \section1 Using OpenGL for Rendering Data
+
+ It is recommended to use OpenGL 2.1 or later for data rendering.
+ If OpenGL ES2 is used (including Angle builds in Windows), the following
+ features are not supported:
+
+ \list
+ \li Shadows
+ \li Antialiasing
+ \li Flat shading for surfaces
+ \li Volumetric objects, because they use 3D textures
+ \endlist
+
+ Only OpenGL ES2 emulation is available for software renderer (that is, when
+ using QCoreApplication::setAttribute(Qt::AA_UseSoftwareOpenGL)).
+
+ \section2 Selecting Rendering Mode
+
+ In QML, you can set the \l{AbstractGraph3D::renderingMode}
+ {AbstractGraph3D.RenderingMode} property to determine whether the graph will
+ be rendered directly on the window background or to an offscreen surface
+ that is then drawn during normal QML item rendering.
+
+ Background rendering modes offer slightly better performance than the
+ indirect rendering mode, at the cost of non-standard QML behavior. For
+ example, the graphs do not obey the z ordering of QML items and they cannot
+ be partially transparent. Therefore, changing the rendering mode is a
+ question of performance versus quality.
+
+ Qt Quick 2 uses a dedicated scenegraph for data rendering, and is therefore
+ the best choice for data visualization.
+
+ \section1 3D Axes
+
+ Qt Data Visualization supports the following axis types:
+
+ \list
+ \li Value axis
+ \li Category axis
+ \endlist
+
+ An axis can be set up to show a line or a grid. Both axis types are
+ specializations of the QAbstract3DAxis class or the AbstractAxis3D QML type.
+
+ A value axis can be given a range of values and segment and subsegment
+ counts to divide the range into. Labels are drawn between each segment.
+ Grid lines are drawn between each segment and each subsegment. The value
+ axis is implemented using the QValue3DAxis class or the ValueAxis3D QML type.
+
+ A category axis has named ranges and adjustable range widths. It is divided
+ into equal-sized categories based on the data window size defined by the
+ axis range. Labels are drawn to the positions of categories, if provided.
+ Grid lines are drawn between categories, if visible. A category axis is
+ implemented using the QCategory3DAxis class or the CategoryAxis3D QML type.
+
+ If no axes are set explicitly for a graph, temporary default axes with no
+ labels are created. These default axes can be modified via axis accessors,
+ but as soon as any axis is set explicitly for a particular orientation, the
+ default axis for that orientation is destroyed.
+
+ All graph types support showing multiple series simultaneously. All the
+ series do not need to contain the same number of rows and columns. Row and
+ column labels are taken from the first series added, unless they are
+ explicitly defined for the row and column axes.
+
+ Axis formatters can be used to customize value axis grid lines and labels.
+ The QValue3DAxisFormatter class and ValueAxis3DFormatter QML type provide
+ formatting rules for a linear value 3D axis. The QLogValue3DAxisFormatter
+ class and the LogValueAxis3DFormatter QML type provide formatting rules for
+ a logarithmic value 3D axis.
+
+ Polar horizontal axes can be used for surface and scatter graphs by setting
+ the \l{QAbstract3DGraph::}{polar} property.
+
+ \section1 3D Themes
+
+ A theme is a built-in collection of UI style related settings applied to all
+ the visual elements of a graph, such as the colors, fonts, and visibility of
+ the elements, as well as the strenght of the light and ambient light.
+
+ Qt Charts comes with the following predefined themes that can be used as
+ basis for custom themes:
+
+ \list
+ \li \e Qt is a light theme with green as the base color.
+ \li \e {Primary colors} is a light theme with yellow as the base color.
+ \li \e Digia is a light theme with gray as the base color.
+ \li \e {Stone moss} is a medium dark theme with yellow as the base
+ color.
+ \li \e {Army blue} is a medium light theme with blue as the base color.
+ \li \e Retro is a medium light theme with brown as the base color.
+ \li \e Ebony is a dark theme with white as the base color.
+ \li \e Isabelle is a dark theme with yellow as the base color.
+ \li \e {User defined} is the default theme that is meant to be
+ customized. For more information, see \l {Default Theme}.
+ \endlist
+
+ Custom themes can also be created from scratch.
+
+ If a graph displays the data from several data series, some settings can be
+ specified separately for each series. For example, different gradients can
+ be specified for different layers of the graph to make it look more
+ realistic. For an example, see \l{Qt Quick 2 Surface Multiseries Example}.
+
+ \section1 Customizing 3D Scenes
+
+ A 3D scene is implemented by using the Q3DScene class or the Scene3D QML
+ type. A scene contains a single active camera, implemented by using the
+ Q3DCamera class or the Camera3D type, and a single active light source,
+ implemented by using the Q3DLight class or the Light3D type. The light
+ source is always positioned in relation to the camera. By default, the light
+ position follows the camera automatically.
+
+ The camera can be customized by specifying its preset position, rotation,
+ and zoom level. For an example, see \l{Qt Quick 2 Scatter Example}.
+
+ \section1 Customizing Items
+
+ Qt Data Visualization has predefined mesh types for bars, items, and
+ surfaces. The mesh type determines how a bar, an item, or a surface looks on
+ a graph. A user-defined mesh can be specified as a Wavefront OBJ geometry
+ definition file. For more variety, a quaternion can be set for mesh
+ rotation.
+
+ In addition to customizing individual items, the QCustom3DItem class or the
+ Custom3DItem QML type can be used to add custom items to graphs. The items
+ have a custom mesh, position, scaling, rotation, and an optional texture.
+
+ The QCustom3DVolume class and the Custom3DVolume QML type can be used to
+ create volume rendered objects to be added to a graph. A volume rendered
+ object is a box with a 3D texture. Three slice planes are supported for the
+ volume, one along each main axis of the volume.
+
+ The The QCustom3DLabel class and the Custom3DLabel QML type implement custom
+ labels with the specified text, font, position, scaling, and rotation. Label
+ colors, borders, and background are determined by the active theme.
+*/
diff --git a/src/datavisualization/doc/src/qtdatavisualization.qdoc b/src/datavisualization/doc/src/qtdatavisualization.qdoc
index 551281d8..72f2302c 100644
--- a/src/datavisualization/doc/src/qtdatavisualization.qdoc
+++ b/src/datavisualization/doc/src/qtdatavisualization.qdoc
@@ -181,9 +181,27 @@
\section1 Interacting with Data
- You can interact with the rendered graph with either mouse or touch to rotate, zoom, or select
- data. For the default mouse controls, see Q3DInputHandler documentation, and for the default
- touch controls, see QTouch3DInputHandler documentation.
+ End users can interact with the rendered graph by using either the mouse or
+ touch to rotate, zoom, or select data. Graphs can be rotated freely by
+ holding down the right mouse button and moving the mouse. Zooming is done by
+ rolling the mouse wheel. Selecting, if enabled, is done by pressing the left
+ mouse button. The scene can be reset to the default camera view by clicking
+ the mouse wheel. In touch devices, rotation is done by tap-and-move,
+ selection by tap-and-hold, and zoom by pinch.
+
+ Qt Data Visualization has default handlers for mouse actions and touch
+ gestures. For the default mouse controls, see Q3DInputHandler, and for
+ the default touch controls, see QTouch3DInputHandler. The default handlers
+ must be disabled when using customized input handlers.
+
+ The \l{Custom Input Example} illustrates how to use a custom input handler
+ to select items upon mouseover instead of mouse click. The information
+ below the mouse cursor is displayed as a popup.
+
+ In addition to perspective projection, orthographic projection can be used
+ to create 2D graphs by replacing the default input handler with one that
+ does not allow rotating the graph and setting the camera to view the graph
+ directly from the side or from the top.
\section1 Data Selection Modes
@@ -211,10 +229,6 @@
\list
\li Some platforms like Android and WinRT cannot handle multiple native windows properly,
so only the Qt Quick 2 graphs are available in practice for those platforms.
- \li Shadows are not supported with OpenGL ES2 (including Angle builds in Windows).
- \li Anti-aliasing doesn't work with OpenGL ES2 (including Angle builds in Windows).
- \li QCustom3DVolume items are not supported with OpenGL ES2 (including Angle builds in
- Windows).
\li Surfaces with non-straight rows and columns do not always render properly.
\li Q3DLight class (and Light3D QML item) are currently not usable for anything.
\li Changing most of Q3DScene properties affecting subviewports currently has no effect.
@@ -224,8 +238,6 @@
"QT += datavisualization" in the pro file. This is because Qt Data Visualization
QML plugin has a dependency to Qt Data Visualization C++ library, which Qt Creator
doesn't automatically add to the deployment package.
- \li Only OpenGL ES2 emulation is available for software renderer (that is, when using
- QCoreApplication::setAttribute(Qt::AA_UseSoftwareOpenGL))
\endlist
*/