The Qwt Developer’s Manual

The Qwt library can be downloaded as a source code archive from the Qwt SourceForge project page. On Linux, Qwt is packaged by many distributions. Strictly speaking, there are several packages for the different Qwt library versions or Qt versions. Details about installing and using the library can be found in Chapter 17.

We start with the qmake project file, in which we set the path for the library’s header files and the library to link against. Here I assume that Qwt was built from the 6.3.0 source archive and installed locally into the default directories (C:\qwt-6.3.0 on Windows and /usr/local/qwt-6.3.0 on Linux/Mac). Information about compiling the library from source and installing it can be found in Chapter 17.

This is a .pro file for a Qwt 6.3.0 installation from source with default settings (see Chapter 17.2).

To use QwtPlot you only need a very minimalistic main.cpp.

The program shows a rather boring (and ugly) diagram window (it will be made more attractive later).

First we add a line, i.e. a diagram curve (header QwtPlotCurve or qwt_plot_curve.h):

In the extended main program, the header for QwtPlotCurve is included first. The curve object itself is created with new on the heap. We read the curve’s data from a text file (2 columns, with a header line). The file spektrum.tsv is included in the archive of the tutorial source code.

Attributes such as line color, title (shown in the legend later), and antialiasing are set (in Chapter 5 all properties of lines are explained in detail).

The function setSamples() sets the line’s data. It is important here that the passed vectors have the same length. This is a parametric curve, i.e. neither the x nor the y values have to be monotonic or follow any other rules. Each x,y value pair defines a point and these points are connected by the line.

The function attach() adds the QwtPlotCurve object to the diagram.

In addition to the code that adds the line, 2 small adjustments were made to the appearance:

The result already looks more like a diagram.

Next we insert a legend (header QwtLegend or qwt_legend.h):

Here, too, the header for the QwtLegend class is included at the top.

The legend is given a modified font here. Further customization of the legend is described in Chapter 9.

The legend can be placed left, right, above or below the drawing canvas, or inside the drawing canvas itself. The placement is specified in the call to insertLegend().

When insertLegend() is called, the plot again takes ownership of the legend object and takes care of freeing the memory.

The QwtText class (header QwtText or qwt_text.h) wraps a QString and adds functionality for rendering mathematical symbols via MathML (see Chapter 12.1).

Grid lines are drawn by the QwtPlotGrid drawing object (header QwtPlotGrid or qwt_plot_grid.h):

The grid itself can be customized with respect to the pen (QPen) for the major and minor grid. The function enableYMin() switches on the minor grid for the Y axis. As with the plot curves, attach() hands the QwtPlotGrid object to QwtPlot, which then takes care of memory management.

By now the diagram already looks quite decent.

QwtPlot has 4 axes built in, called:

By default, the axes xBottom and yLeft are visible, as in the plot used so far.

Every drawing element in the plot (curves, markers, …​) is assigned to one or more axes. In our introductory example the QwtPlotCurve uses the axes xBottom and yLeft by default.

The axes can be configured as follows.

The title of each axis is again set via a QwtText object (contains text and font). The font for the numbers on the axes themselves is changed via setAxisFont().

The axes themselves can be customized in many ways, see Chapter 11.

By default, the axes automatically adjust to the value range of the displayed curves. Of course you can change this too, see Chapter 11.

QwtPlot can also use logarithmic axes. For this you have to plug in a different scale computation class, the QwtLogScaleEngine (header QwtLogScaleEngine or qwt_scale_engine.h):

When setAxisScaleEngine() is called, the plot again takes ownership of the object and then takes care of freeing the memory.

Chapter 11 describes the details of the ScaleEngine and gives further examples.

Another drawing element that you need from time to time is horizontal or vertical marker lines. As an example, let’s add such a line to the plot (header QwtPlotMarker or qwt_plot_marker.h):

Markers also have many configuration options, see Chapter 10.

Now the diagram itself is finished and we turn to user interaction.

The zoom functionality is added via the QwtPlotZoomer class (header QwtPlotZoomer or qwt_plot_zoomer.h):

When you move the mouse over the diagram, you already see a changed cursor and, thanks to the call setTrackerMode(QwtPlotPicker::AlwaysOn), you now also see the x and y values (of the axes xBottom and yLeft) under the cursor.

You can zoom in by holding down the left mouse button and dragging a zoom rectangle. You can also do this several times in a row. QwtPlot internally remembers these zoom levels. You can zoom out by clicking the right mouse button, which always zooms out one zoom level.

There is one more peculiarity in the source code. Whereas the plot elements so far have always been added with member functions of the QwtPlot class, or via attach(), the zoomer object is, analogously to Qt classes, given as a child object of the drawing canvas and registers itself through that as an interactive element with the plot.

So that the zoomer knows which axes are to be manipulated when zooming, you have to specify the x and y axis in the constructor. If, for example, you want to zoom both y axes at the same time, you need two QwtPlotZoomer objects.

If you want to interactively move the section of a zoomed-in plot, you can add the QwtPlotPanner (header QwtPlotZoomer or qwt_plot_zoomer.h):

As with QwtPlotZoomer, the object is added as a child object of the canvas widget. It is customary to move screen content with the middle mouse button held down, so you set that with setMouseButton().

This concludes the introductory tutorial. With QwtPlot you can already create a fully functional and interactive diagram with just a few steps.

In this tutorial, QwtPlot was also the application widget. But if you want to insert QwtPlot into existing Designer form classes, there are various techniques:

These methods are described in Chapter 17.5.

Individual chapters are dedicated to all diagram types and further plot properties. For QwtPlot, only the functionality shipped with QwtPlot and the associated classes is covered first. Later chapters show how to extend the plot functionality by overriding/replacing the built-in functions.

The diagram itself is a Cartesian diagram with at most 4 axes, identified by the following enumeration values:

The primary task of these axes is to convert between plot coordinates (x,y) and screen coordinates. Each of the four axes can be configured individually, which affects the min/max values and the axis scaling.

Within the drawing canvas you can now draw a wide variety of elements, e.g.:

All of these objects are derived from the base class QwtPlotItem and therefore share certain common properties.

In a single diagram you can combine all kinds of elements, i.e. you can also display line diagrams together with bars, symbols and markers.

The diagram elements are positioned via plot coordinates. The conversion into screen coordinates, i.e. the concrete position on the drawing canvas, is done using the respectively assigned x and y axis. Since there are two x axes and two y axes, when displaying a diagram element at a particular x,y data point you necessarily need an assignment to one x axis and one y axis. This property is set on the individual drawing elements, with xBottom and yLeft being selected by default.

QwtPlotItem also declares and implements the virtual functions for drawing as well as for computing important layout data. This will be explained in more detail later in the advanced chapters. But now on to the individual drawing elements and the diagram types built from them.

All drawing elements are always created on the heap with new and added to the actual QwtPlot via the member function QwtPlotItem::attach(plot).

Drawing elements can be removed using the function QwtPlotItem::detach().

You can also remove all drawing elements of a particular type:

The first argument of detachItems() is the drawing element type. With the second argument you specify whether the object itself should be deleted, or only removed from the plot. In the latter case you have to take care of freeing the memory yourself again.

Configuration of a QwtPlotCurve as a line:

Configuration of a QwtPlotCurve as vertical sticks:

Alternatively, you can also draw the sticks horizontally. For this you additionally have to set the orientation with QwtPlotSeriesItem::setOrientation():

If the data should not be connected linearly but rather represent steps, you can use the line type Steps. The additional attribute QwtPlotCurve::Inverted specifies whether the step should be at the end of the interval or at the beginning of the interval. Curve attributes are set with QwtPlotCurve::setCurveAttribute():

If you look at the input data:

you notice that in the first interval, i.e. between x=1..2, the value y2=4 is drawn, and at position x1=1 the connecting line between y1=5 and y2=4 is drawn.

If you want to draw the first y value directly in the first interval (that would be the more natural expectation), you have to set the Inverted attribute:

At the respective x,y coordinates you can also simply draw only dots (even just single pixels). This is very fast compared to drawing symbols (see Chapter 5.3) and can be used for larger point clouds.

If you want to draw a curve exclusively with symbols (see Chapter 5.3), you can also switch off the drawing of the polyline completely:

There are numerous built-in symbol shapes (in bold in the diagram title is the respective QwtSymbol::Style enumeration name):

Symbols do not always have to be square. If you set the size of a symbol with

then width=height=10 is used automatically. Alternatively, you can also define a rectangle as the size:

That is also why there are no separate line styles for circle and ellipse or rectangle and square.

You can set arbitrary custom symbol shapes by using the QPainterPath class. The following example generates a light bulb symbol:

You can render and display your own SVG files. For this you only have to read in/define an SVG file and set it as a symbol:

Sometimes the anchor point of the SVG image is not in the center, as in the example above:

You can change the anchor point, i.e. the centering point of the symbol, with QwtSymbol::setPinPoint(). The coordinates of the pin point are measured from the left/top of the SVG image:

As an alternative to custom vector graphic symbols, you can also use arbitrary images as symbols. This is done analogously to the SVG symbols:

The QwtPlotCurve class has various paint attributes that configure the algorithms used in more detail. Here is a short list first; the individual attributes and their effects are described in more detail later:

By using the data filter FilterPoints you can, with very large series data, only really draw the data that affects the diagram. If, for example, 100 data points land on the same pixel, you do not need to draw them all. Filtering out invisible points and line segments depends, of course, on the zoom level and is therefore integrated into the drawing routine of QwtPlotCurve.

The paint attribute QwtPlotCurve::FilterPoints is set by default and causes duplicate points to be filtered out already when transforming the data series coordinates into screen coordinates (this is done by the QwtPointMapper class). If a data series contains, for example, 100000 evenly distributed points along the x axis and is drawn on a 1000-pixel-wide plot, then 100 points each share an x pixel coordinate. If, after the coordinate conversion, two consecutive points have identical pixel coordinates, the duplicate points are removed. This function, switched on by default, already makes a big difference to the drawing speed.

To illustrate this, here is a small test program for the filter functions:

The test program generates 10 million data points (several sine waves) and then draws them into a 1000x800 pixel diagram, initially without the point filter. For this, in the line

the paint attribute FilterPoints is switched off. The drawing time for the curve, including the time for the data filtering, is measured in the derived QwtPlotCurve and the small wrapper around the central drawCurve() function.

On my machine the program outputs about 650 ms in the release build. All 10 million points are really taken into the polyline to be drawn and drawn on the painter (which of course discards line segments of length 0, but needs some time for that).

If you now switch the FilterPoints attribute back on, then after the filtering the polygon contains only about 24500 points and the drawing takes about 300 ms.

If data series are very noisy and at the same time contain very large amounts of data, then several line segments can overlap. For example, several lines with the same x screen coordinate are then drawn on top of each other, even though a single line drawn between the minimum and maximum y coordinate would suffice.

The paint attribute FilterPointsAggressive switches on a pre-computation that performs exactly this kind of optimization (also implemented in the QwtPointMapper class) and turns several overlapping vertical line segments into a single line (which is also why this optimization only makes sense for the line type QwtPlotCurve::Lines).

To test this, we modify the program above and generate a strongly noisy curve:

Without FilterPointsAggressive, drawing takes about 1500 ms. Although the data series consists of "only" 1 million points, the line segments are significantly longer than with the sine wave and it takes longer to draw them. The paint attribute FilterPoints can also hardly throw out any points because of the strongly fluctuating y values (the line segments almost never have a length of 0).

If you now switch on the attribute with

the drawing time shortens to about 32 ms !!!! After the filtering, the polygon to be drawn has only about 3670 points left.

If you look at the diagrams with and without FilterPointsAggressive in comparison, you see minor differences.

With antialiasing you see differences in the semi-transparent segments. Without antialiasing you have to look very closely to see the small differences.

(For comparison, download both images and display them alternately in an image viewer, then you can see the small differences.)

Depending on the choice of the plot section, to be set via axis scaling (see Chapter 11) or interactively via the plot zoomer (see Chapter 13), sometimes only parts of curves are drawn. In this case it makes sense to limit the polygon to the visible ranges only. The QwtPlotCurve class offers this functionality by switching on the paint attribute QwtPlotCurve::ClipPolygons.

By default the QwtPlotCurve::ClipPolygons attribute is switched on. The clipping is, by the way, applied only after the point filter algorithm, so that a data reduction in that step has a positive effect on the time for the clipping.

Interestingly, polygon clipping affects rendering performance only imperceptibly when rendering to the screen.

For the 10 million point sine curve plot above (antialiasing on, FilterPoints on, FilterPointsAggressive off, ClipPolygons on), the drawing time for the complete diagram is about 300 ms. Zoomed in with

the render time increases to about 370 ms. If you now switch off ClipPolygons, then it takes 290 ms for the complete plot and 410 ms for the zoomed-in plot.

The difference between 300 ms and 290 ms for the complete plot is due to the overhead for the polygon clipping function, which of course has no effect for the fully visible plot.

In the strongly zoomed-in state, the plot with polygon clipping switched on draws about 40 ms faster, which should, however, rarely be significant.

Let’s first look at the QwtSplineCurveFitter. This class encapsulates an algorithm that computes a smooth course from the given support points of the curve. There are various mathematical algorithms for this.

Each of these algorithms is implemented in a class derived from QwtSpline.

The result can best be illustrated with a simple parametric data set:

It is important that the use of the curve fitter/filter is switched on explicitly with

The Qwt library comes with a whole range of different algorithms and matching implementations:

For comparison, the various spline algorithms are shown:

This curve filter is intended for polar diagrams, see [sec:polarPlots].

As already described in Chapter 5.6, the QwtPlotCurve class already comes with a number of its own functions to filter out unnecessary points and line segments. These are, however, primarily useful for raster output, i.e. on screen.

When outputting to vector formats (PDF/SVG), the paint attribute filters QwtPlotCurve::FilterPoints or QwtPlotCurve::FilterPointsAggressive are not used, since they only work with rounded coordinates.

For data reduction on vector exports, however, you can use an alternative point filter algorithm to remove points that are not needed. Such a data reduction filter is implemented in the QwtWeedingCurveFitter class. This one really is a filter and removes data points according to certain rules.

Concretely, the algorithm tries to remove all points that are already sufficiently well approximated by linear interpolation between the neighboring points.

For testing, a sine wave is generated again:

The example from Chapter 5.6 is now extended with the QwtWeedingCurveFitter:

This curve filter is used like the previous curve filters, and here, too, you must not forget to set the curve attribute QwtPlotCurve::Fitted.

The WeedingCurveFitter reduces the number of data points significantly, as here with rather smooth curves. In the example above, of the originally 10 million points, just 78 remain. To visualize the resulting support points, a second data series was created, where the data was directly reduced in advance from the data points with the QwtWeedingCurveFitter class (see also Chapter 5.7.3.2).

An important parameter for the algorithm is the allowed tolerance, to be set in the constructor or via QwtWeedingCurveFitter::setTolerance(double). This tolerance is an absolute value based on the y coordinates in the passed polygon. Depending on the order of magnitude of the y values of the points, the points are filtered differently. This means that with larger plots and correspondingly larger pixel resolution in the y direction, more support points are also generated and the quality of the diagram does not suffer.

The tolerance parameter roughly has the following effect when the y values are in the order of magnitude of 100 (as in the example above).

The second parameter of the QwtWeedingCurveFitter class is the chunk size, set with QwtWeedingCurveFitter::setChunkSize(int).

The original polygon is split into pieces of the given chunk size and the algorithm is applied to the individual pieces individually. In doing so, at least one point is generated per chunk. So if you were to choose a chunk size of 100000 for the example above, you would get 200 points (even with tolerance 10). The algorithm then has somewhat less to do and is finished after about 50 ms, instead of after about 270 ms as before. But if you consider that here 10 million points are turned into a very small polygon with fewer than 100 points, without the data quality visibly suffering, then the algorithm is (especially on today’s hardware) overall very fast.

First you have to determine the zero crossings of the curves and insert new support points with y=0 at these positions. The function addZeroCrossings() does this:

In order to be able to add the data values, the support points must match. So a uniform X value grid is determined and the respective missing values are interpolated.

Now you can add the data series. The positive and the negative parts are added separately, and you get, in effect, two stacked line series that are, however, drawn into the same diagram at the same time.

Further up I already pointed out that instead of QwtIntervalCurve you can also use filled curves. In this case the plot code after computeStackedLinesWithNegative() looks like this:

The result looks almost identical, with the difference that with the interval curves a boundary line is also drawn along the lower edge.

Which method is faster now? Here is an example from practice: initially 8760 hourly values; after adding zero crossings and unifying the grid there are just under 10000 data points.

Time for re-rendering the plot after resizing to 1920x1080 resolution:

In this mode, set by

the size of the bars is determined based on the size of the drawing canvas and the configured margin and spacing values.

The bars, the spacing and the margins fill the drawing canvas completely. As you can see in the right diagram, this stays that way even when zooming into the diagram.

The additional parameter setLayoutHint() defines the number of pixels that a bar should be at least wide. This lets you prevent the bars from eventually disappearing completely when the plot size is reduced. The following example shows what happens with a larger LayoutHint in AutoAdjustSamples mode:

In this layout mode the bar width is set based on the current x axis scaling. If, in this layout mode, you set the LayoutHint to 0.5, then a bar is drawn exactly half as wide as an axis tick and then centered on the axis tick. So the X axis is used to convert the 0.5 in plot coordinates into pixel widths of the drawing canvas.

When zooming in, too, the bar width always follows the X axis scaling.

In this mode the bar widths are determined as a function of (as a percentage of) the drawing canvas size. To set the LayoutHint parameter, you should consider how many bars will at most be visible in the diagram.

When zooming in, the bar width stays constant and changes only when the plot size changes.

Apart from special requirements, for most cases the layout policy QwtPlotAbstractBarChart::ScaleSamplesToAxes is recommended. Both when resizing the plot and when zooming, the plot behaves as you would expect.

If you really want to have always the same spacing between the bars, no matter how large the plot is or how far you zoom in, then the layout policy QwtPlotAbstractBarChart::AutoAdjustSamples is recommended.