3D waterfall plot item with a built-in sliding window More...

#include <qwt3d_waterfall.h>

Inheritance diagram for Qwt3DWaterfall:

Classes
class	PrivateData

Public Types
enum	PlotStyle { Ribbon , RibbonMesh , Wireframe , Tube }
	Geometry style of a trace. More...

enum	ColorMode { ByDepth , ByAmplitude , Solid }
	Where the per-vertex color comes from. More...

enum	DepthOrder { NewestInFront , NewestBehind }
	Depth direction of the sliding window. More...

Public Member Functions
	Qwt3DWaterfall ()
	Returns the sliding window size.

int	traceCapacity () const
	Returns the number of visible traces (window size)

void	setTraceCapacity (int count)
	Sets the window size (>= 1); excess traces are dropped.

int	traceCount () const
	Returns how many traces are currently stored (<= traceCapacity)

int	samplesPerTrace () const
	Returns the bin count of the stored traces (0 before the first push)

void	pushTrace (const double *values, int count)
	Appends one trace (newest); drops the oldest when the window is full.

void	pushTrace (const QVector< double > &values)
	Appends one trace from a QVector.

void	clear ()
	Clears all traces (capacity, style and colors are kept)

void	setBinValues (const QVector< double > &x)
	Sets the x value of every bin (empty means 0..samplesPerTrace-1)

QVector< double >	binValues () const
	Returns the current bin values.

DepthOrder	depthOrder () const
	Returns the depth order.

void	setDepthOrder (DepthOrder order)
	Sets the depth order.

PlotStyle	plotStyle () const
	Returns the geometry style.

void	setPlotStyle (PlotStyle style)
	Sets the geometry style.

ColorMode	colorMode () const
	Returns the color mode.

void	setColorMode (ColorMode mode)
	Sets the color mode.

void	setColor (RGBA color)
	Sets the solid color (Solid mode, and the default outline color)

RGBA	color () const
	Returns the solid color.

void	setDataColor (Qwt3DColor *color)
	Sets the data color functor (takes ownership)

const Qwt3DColor *	dataColor () const
	Returns the data color functor.

void	invalidateColors ()
	Marks colors stale, rebuilding the VBO on the next draw.

void	setColorRange (double min, double max)
	Fixes the color range.

void	resetColorRange ()
	Returns to the automatic color range.

bool	hasFixedColorRange () const
	Returns true when a fixed color range is active.

double	baseline () const
	Returns the ribbon baseline.

void	setBaseline (double value)
	Sets the ribbon baseline.

void	resetBaseline ()
	Lets the baseline follow the amplitude minimum again.

double	opacity () const
	Returns the ribbon alpha (0..1, default 1)

void	setOpacity (double alpha)
	Sets the ribbon alpha.

RGBA	outlineColor () const
	Returns the outline color (RibbonMesh / Wireframe / Tube outline)

void	setOutlineColor (RGBA color)
	Sets the outline color.

double	outlineWidth () const
	Returns the outline line width.

void	setOutlineWidth (double width)
	Sets the outline line width (Lines-based styles only)

int	rtti () const override
	Runtime type information.

void	draw () override
	Draw the item using the current GL context.

ParallelEpiped	hull () const override
	Returns the bounding hull of the waterfall.

void	populateLegendColors (ColorVector &colors) const override
	Populates the legend colors.

Public Member Functions inherited from Qwt3DPlotItem
	Qwt3DPlotItem ()
	Default constructor.

virtual	~Qwt3DPlotItem ()
	Destructor — detaches from any plot.

void	attach (Qwt3DPlot *plot)
	Attach the item to a plot.

void	detach ()
	Detach the item from its plot.

Qwt3DPlot *	plot () const
	Get the plot this item is attached to.

void	setTitle (const QString &title)
	Set the item title.

QString	title () const
	Get the item title.

void	setZ (double z)
	Set the z-order value (controls draw sequence)

double	z () const
	Get the z-order value.

void	setVisible (bool on)
	Set item visibility.

bool	isVisible () const
	Check if the item is visible.

virtual void	itemChanged ()
	Notify the plot that the item has changed.

Detailed Description

3D waterfall plot item with a built-in sliding window

A waterfall renders a sequence of one-dimensional traces (spectra, chromatograms, ...) as stacked curves along the depth axis. The item owns the storage: push one trace per sample interval with pushTrace() and the item maintains the sliding window, the depth numbering, the ribbon geometry and the color mapping.

The axes follow the 3D module convention (the value axis is z, as in Qwt3DSurface): x = bin value, y = trace position in the window (depth), z = amplitude. The depth coordinate of a trace is its slot index inside the window, so the hull y-range grows monotonically from [0,0] to [0, traceCapacity()-1] and then stays stable - no per-frame depth autoscale jitter, no user-side depth bookkeeping. The amplitude (z) range still follows the data; fix it with setColorRange() for stable amplitude colors in a live waterfall.

auto* waterfall = new Qwt3DWaterfall();
waterfall->attach(plot);
waterfall->setTraceCapacity(64);
waterfall->setPlotStyle(Qwt3DWaterfall::RibbonMesh);
waterfall->setColorMode(Qwt3DWaterfall::ByAmplitude);
waterfall->setColorRange(0.0, 1.0);      // fix the range, no autoscale jitter
 
// per timer tick (30 Hz):
waterfall->pushTrace(frame);             // QVector<double>, 256 bins

See also: Qwt3DPlotItem, Qwt3DLine, Qwt3DColor

Member Enumeration Documentation

◆ ColorMode

enum Qwt3DWaterfall::ColorMode

Where the per-vertex color comes from.

Enumerator
ByDepth	Colormap over the trace position in the window (default)
ByAmplitude	Colormap over the sample value.
Solid	Single color (setColor)

◆ DepthOrder

enum Qwt3DWaterfall::DepthOrder

Depth direction of the sliding window.

Enumerator
NewestInFront	The newest trace sits at the largest y (default)
NewestBehind	The newest trace sits at y == 0.

◆ PlotStyle

enum Qwt3DWaterfall::PlotStyle

Geometry style of a trace.

Enumerator
Ribbon	Filled curtain from the baseline up to the trace (default)
RibbonMesh	Ribbon plus a line outline drawn on top.
Wireframe	Line outline only (no fill)
Tube	Lit tube swept along the trace (thick strokes)

Constructor & Destructor Documentation

◆ Qwt3DWaterfall()

Qwt3DWaterfall::Qwt3DWaterfall ( )

Returns the sliding window size.

Returns: Number of trace slots (>= 1)

Member Function Documentation

◆ baseline()

double Qwt3DWaterfall::baseline ( ) const

Returns the ribbon baseline.

Returns the ribbon baseline on the amplitude (z) axis (defaults to the current amplitude minimum)

Returns: The fixed baseline, or the current amplitude minimum when unset

◆ binValues()

QVector< double > Qwt3DWaterfall::binValues ( ) const

Returns the current bin values.

Returns: Bin positions, empty when the bins default to 0..M-1

◆ clear()

void Qwt3DWaterfall::clear ( )

Clears all traces (capacity, style and colors are kept)

Clears all traces.

The capacity, bin values, styles and colors are kept. The bin count is re-established by the next pushTrace().

◆ color()

RGBA Qwt3DWaterfall::color ( ) const

Returns the solid color.

Returns: Color used by the Solid mode

◆ colorMode()

Qwt3DWaterfall::ColorMode Qwt3DWaterfall::colorMode ( ) const

Returns the color mode.

Returns: ByDepth, ByAmplitude or Solid

◆ dataColor()

const Qwt3DColor * Qwt3DWaterfall::dataColor ( ) const

Returns the data color functor.

Returns: The functor set with setDataColor(), nullptr if none was set

◆ depthOrder()

Qwt3DWaterfall::DepthOrder Qwt3DWaterfall::depthOrder ( ) const

Returns the depth order.

Returns the depth direction of the sliding window.

Returns: NewestInFront (newest trace at the largest z) or NewestBehind

◆ draw()

void Qwt3DWaterfall::draw ( )

overridevirtual

Draw the item using the current GL context.

Implements Qwt3DPlotItem.

◆ hasFixedColorRange()

bool Qwt3DWaterfall::hasFixedColorRange ( ) const

Returns true when a fixed color range is active.

Returns: true after setColorRange(), false after resetColorRange()

◆ hull()

ParallelEpiped Qwt3DWaterfall::hull ( ) const

overridevirtual

Returns the bounding hull of the waterfall.

Returns: x from the bin values, y = [0, traceCount()-1] (depth), z = [min(amplitude, baseline), amplitude max]; degenerate to (0,0,0)-(0,0,0) when empty

Implements Qwt3DPlotItem.

◆ invalidateColors()

void Qwt3DWaterfall::invalidateColors ( )

Marks colors stale, rebuilding the VBO on the next draw.

Marks the baked per-vertex colors as stale.

Colors are baked into the VBO at build time, so an in-place mutation of the data color functor needs this call (or any other setter) to take effect on the next draw.

◆ opacity()

double Qwt3DWaterfall::opacity ( ) const

Returns the ribbon alpha (0..1, default 1)

Returns the ribbon alpha.

Returns: Alpha in [0, 1] (default 1)

◆ outlineColor()

RGBA Qwt3DWaterfall::outlineColor ( ) const

Returns the outline color (RibbonMesh / Wireframe / Tube outline)

Returns the outline color.

Returns: Color of the RibbonMesh / Wireframe outline

◆ outlineWidth()

double Qwt3DWaterfall::outlineWidth ( ) const

Returns the outline line width.

Returns: Line width in pixels (Lines-based styles only)

◆ plotStyle()

Qwt3DWaterfall::PlotStyle Qwt3DWaterfall::plotStyle ( ) const

Returns the geometry style.

Returns: Ribbon, RibbonMesh, Wireframe or Tube

◆ populateLegendColors()

void Qwt3DWaterfall::populateLegendColors ( ColorVector & colors ) const

overridevirtual

Populates the legend colors.

Parameters

[out] colors Legend color vector to fill

One waterfall is one item and contributes one legend gradient: the data color functor vector (with the active range pushed), or the solid color in Solid mode / before a functor exists.

Reimplemented from Qwt3DPlotItem.

◆ pushTrace() [1/2]

void Qwt3DWaterfall::pushTrace	(	const double *	values,
		int	count
	)

Appends one trace (newest); drops the oldest when the window is full.

Appends one trace as the newest window entry.

Parameters

values	Sample values of the trace
count	Number of samples in values

The first push fixes samplesPerTrace(); later traces are fitted into the established bin count (longer ones truncated, shorter ones zero-padded) so the window width (and the hull x-range) never jitters. When the window is full the oldest trace is dropped; the surviving slots are rotated by cheap QVector moves, never deep copies.

◆ pushTrace() [2/2]

void Qwt3DWaterfall::pushTrace ( const QVector< double > & values )

Appends one trace from a QVector.

Appends one trace as the newest window entry.

Parameters

values Sample values of the trace

See also: pushTrace(const double*, int)

◆ rtti()

int Qwt3DWaterfall::rtti ( ) const

overridevirtual

Runtime type information.

Returns: Rtti_Plot3DWaterfall (= 1004)

Reimplemented from Qwt3DPlotItem.

◆ samplesPerTrace()

int Qwt3DWaterfall::samplesPerTrace ( ) const

Returns the bin count of the stored traces (0 before the first push)

Returns the bin count of the stored traces.

Returns: Number of samples per trace, 0 before the first pushTrace()

◆ setBaseline()

void Qwt3DWaterfall::setBaseline ( double value )

Sets the ribbon baseline.

Parameters

value The baseline y value

◆ setBinValues()

void Qwt3DWaterfall::setBinValues ( const QVector< double > & x )

Sets the x value of every bin (empty means 0..samplesPerTrace-1)

Sets the x value of every bin.

Parameters

x	Bin positions; an empty vector means 0..samplesPerTrace-1

◆ setColor()

void Qwt3DWaterfall::setColor ( RGBA color )

Sets the solid color (Solid mode, and the default outline color)

Sets the solid color.

Parameters

color Color used by the Solid mode

◆ setColorMode()

void Qwt3DWaterfall::setColorMode ( ColorMode mode )

Sets the color mode.

Parameters

mode	The new color mode

ByAmplitude retargets a Qwt3DColorMapColor data functor to the z coordinate (via setSourceAxis(ColorFromZ)), ByDepth retargets it to y (the depth axis). A functor of a different type is left untouched; its owner decides how to interpret the (x, y, z) argument.

◆ setColorRange()

void Qwt3DWaterfall::setColorRange	(	double	min,
		double	max
	)

Fixes the color range.

Fixes the color range (disables the automatic range); essential for stable amplitude colors in a live waterfall

Parameters

min	Lower bound of the colormap input range
max	Upper bound of the colormap input range

A fixed range disables the automatic (per-frame) range derivation, which is essential for stable amplitude colors in a live waterfall.

◆ setDataColor()

void Qwt3DWaterfall::setDataColor ( Qwt3DColor * color )

Sets the data color functor (takes ownership)

Sets the data color functor.

Parameters

color The new functor (the item takes ownership)

A Qwt3DColorMapColor functor is retargeted to the source axis matching the current color mode (y for ByAmplitude, z otherwise).

◆ setDepthOrder()

void Qwt3DWaterfall::setDepthOrder ( DepthOrder order )

Sets the depth order.

Sets the depth direction of the sliding window.

Parameters

order NewestInFront or NewestBehind

The newest trace either sits at the largest z (the window moves away from the viewer) or at z == 0 (the window moves towards the viewer). Either way the hull z-range stays [0, count-1].

◆ setOpacity()

void Qwt3DWaterfall::setOpacity ( double alpha )

Sets the ribbon alpha.

Parameters

alpha Alpha in [0, 1]; values outside are clamped

Alpha < 1 enables blended drawing. The slots are drawn from the oldest to the newest trace, which is the recommended front-to-back order for the default camera; view nearly parallel to the curtains can still produce interpenetration artifacts (see the docs).

◆ setOutlineColor()

void Qwt3DWaterfall::setOutlineColor ( RGBA color )

Sets the outline color.

Parameters

color Color of the RibbonMesh / Wireframe outline

◆ setOutlineWidth()

void Qwt3DWaterfall::setOutlineWidth ( double width )

Sets the outline line width (Lines-based styles only)

Sets the outline line width.

Parameters

width Line width in pixels (> 1 is not guaranteed in Core profile)

◆ setPlotStyle()

void Qwt3DWaterfall::setPlotStyle ( PlotStyle style )

Sets the geometry style.

Parameters

style The new geometry style

RibbonMesh draws its outline after the fill, regardless of the item's z value, so the outline is never hidden by its own curtain.

◆ setTraceCapacity()

void Qwt3DWaterfall::setTraceCapacity ( int count )

Sets the window size (>= 1); excess traces are dropped.

Sets the sliding window size.

Parameters

count New window size (clamped to >= 1)

When shrinking, the oldest traces are dropped so the newest min(traceCount, count) traces survive. The stored traces keep their relative order.

◆ traceCount()

int Qwt3DWaterfall::traceCount ( ) const

Returns how many traces are currently stored (<= traceCapacity)

Returns how many traces are currently stored.

Returns: Trace count, <= traceCapacity()

The documentation for this class was generated from the following files:

/home/runner/work/QWT/QWT/src/plot3d/qwt3d_waterfall.h
/home/runner/work/QWT/QWT/src/plot3d/qwt3d_waterfall.cpp

Classes

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ ColorMode

◆ DepthOrder

◆ PlotStyle

Constructor & Destructor Documentation

◆ Qwt3DWaterfall()

Member Function Documentation

◆ baseline()

◆ binValues()

◆ clear()

◆ color()

◆ colorMode()

◆ dataColor()

◆ depthOrder()

◆ draw()

◆ hasFixedColorRange()

◆ hull()

◆ invalidateColors()

◆ opacity()

◆ outlineColor()

◆ outlineWidth()

◆ plotStyle()

◆ populateLegendColors()

◆ pushTrace() [1/2]

◆ pushTrace() [2/2]

◆ rtti()

◆ samplesPerTrace()

◆ setBaseline()

◆ setBinValues()

◆ setColor()

◆ setColorMode()

◆ setColorRange()

◆ setDataColor()

◆ setDepthOrder()

◆ setOpacity()

◆ setOutlineColor()

◆ setOutlineWidth()

◆ setPlotStyle()

◆ setTraceCapacity()

◆ traceCount()