QGIS API Documentation  3.37.0-Master (a5b4d9743e8)
Public Member Functions | Static Public Member Functions | List of all members
QgsMultiRenderChecker Class Reference

This class allows checking rendered images against comparison images. More...

#include <qgsmultirenderchecker.h>

Public Member Functions

 QgsMultiRenderChecker ()
 Constructor for QgsMultiRenderChecker. More...
 
virtual ~QgsMultiRenderChecker ()=default
 
QString controlImagePath () const
 Returns the path to the control images. More...
 
QString markdownReport () const
 Returns a markdown report for this test. More...
 
QString report () const
 Returns a HTML report for this test. More...
 
bool runTest (const QString &testName, unsigned int mismatchCount=0)
 Test using renderer to generate the image to be compared. More...
 
void setColorTolerance (unsigned int colorTolerance)
 Set tolerance for color components used by runTest() Default value is 0. More...
 
void setControlName (const QString &name)
 Base directory name for the control image (with control image path suffixed) the path to the image will be constructed like this: controlImagePath + '/' + mControlName + '/' + mControlName + '.png'. More...
 
void setControlPathPrefix (const QString &prefix)
 Sets the path prefix where the control images are kept. More...
 
void setExpectFail (bool expectFail)
 Sets whether the comparison is expected to fail. More...
 
void setFileFunctionLine (const QString &file, const QString &function, int line)
 Sets the source file, function and line from where the test originates. More...
 
void setMapSettings (const QgsMapSettings &mapSettings)
 Set the map settings to use to render the image. More...
 
void setRenderedImage (const QString &renderedImagePath)
 Set the path to the rendered image. More...
 
void setSizeTolerance (int xTolerance, int yTolerance)
 Sets the largest allowable difference in size between the rendered and the expected image. More...
 

Static Public Member Functions

static void drawBackground (QImage *image)
 Draws a checkboard pattern for image backgrounds, so that opacity is visible without requiring a transparent background for the image. More...
 

Detailed Description

This class allows checking rendered images against comparison images.

Its main purpose is for the unit testing framework.

It will either

This image will then be compared against one or several images in a folder inside the control directory (tests/testdata/control_images/{controlName}).

There are modes for single and for multiple reference images.

For every control image there may be one or several randomly named anomaly images defining allowed anomalies. For every control image, the allowed mismatch and color tolerance values will be calculated individually.

Definition at line 55 of file qgsmultirenderchecker.h.

Constructor & Destructor Documentation

◆ QgsMultiRenderChecker()

QgsMultiRenderChecker::QgsMultiRenderChecker ( )

Constructor for QgsMultiRenderChecker.

Definition at line 22 of file qgsmultirenderchecker.cpp.

◆ ~QgsMultiRenderChecker()

virtual QgsMultiRenderChecker::~QgsMultiRenderChecker ( )
virtualdefault

Member Function Documentation

◆ controlImagePath()

QString QgsMultiRenderChecker::controlImagePath ( ) const

Returns the path to the control images.

Definition at line 243 of file qgsmultirenderchecker.cpp.

◆ drawBackground()

static void QgsMultiRenderChecker::drawBackground ( QImage *  image)
inlinestatic

Draws a checkboard pattern for image backgrounds, so that opacity is visible without requiring a transparent background for the image.

Definition at line 166 of file qgsmultirenderchecker.h.

◆ markdownReport()

QString QgsMultiRenderChecker::markdownReport ( ) const

Returns a markdown report for this test.

The report will be empty if the test was successfully run.

See also
report()
Since
QGIS 3.34

Definition at line 217 of file qgsmultirenderchecker.cpp.

◆ report()

QString QgsMultiRenderChecker::report ( ) const

Returns a HTML report for this test.

The report will be empty if the test was successfully run.

See also
markdownReport()

Definition at line 189 of file qgsmultirenderchecker.cpp.

◆ runTest()

bool QgsMultiRenderChecker::runTest ( const QString &  testName,
unsigned int  mismatchCount = 0 
)

Test using renderer to generate the image to be compared.

Parameters
testName- to be used as the basis for writing a file to e.g. /tmp/theTestName.png
mismatchCount- defaults to 0 - the number of pixels that are allowed to be different from the control image. In some cases rendering may be non-deterministic. This parameter allows you to account for that by providing a tolerance.
Note
make sure to call setExpectedImage and setMapSettings first

Definition at line 55 of file qgsmultirenderchecker.cpp.

◆ setColorTolerance()

void QgsMultiRenderChecker::setColorTolerance ( unsigned int  colorTolerance)
inline

Set tolerance for color components used by runTest() Default value is 0.

Parameters
colorToleranceThe maximum difference for each color component including alpha to be considered correct.

Definition at line 114 of file qgsmultirenderchecker.h.

◆ setControlName()

void QgsMultiRenderChecker::setControlName ( const QString &  name)

Base directory name for the control image (with control image path suffixed) the path to the image will be constructed like this: controlImagePath + '/' + mControlName + '/' + mControlName + '.png'.

Definition at line 28 of file qgsmultirenderchecker.cpp.

◆ setControlPathPrefix()

void QgsMultiRenderChecker::setControlPathPrefix ( const QString &  prefix)

Sets the path prefix where the control images are kept.

Definition at line 45 of file qgsmultirenderchecker.cpp.

◆ setExpectFail()

void QgsMultiRenderChecker::setExpectFail ( bool  expectFail)
inline

Sets whether the comparison is expected to fail.

Since
QGIS 3.28

Definition at line 98 of file qgsmultirenderchecker.h.

◆ setFileFunctionLine()

void QgsMultiRenderChecker::setFileFunctionLine ( const QString &  file,
const QString &  function,
int  line 
)

Sets the source file, function and line from where the test originates.

Since
QGIS 3.36

Definition at line 33 of file qgsmultirenderchecker.cpp.

◆ setMapSettings()

void QgsMultiRenderChecker::setMapSettings ( const QgsMapSettings mapSettings)

Set the map settings to use to render the image.

Parameters
mapSettingsThe map settings

Definition at line 50 of file qgsmultirenderchecker.cpp.

◆ setRenderedImage()

void QgsMultiRenderChecker::setRenderedImage ( const QString &  renderedImagePath)
inline

Set the path to the rendered image.

If this is not set or set to null QString, an image will be rendered based on the provided mapsettings

Parameters
renderedImagePathA path to the rendered image with which control images will be compared

Definition at line 91 of file qgsmultirenderchecker.h.

◆ setSizeTolerance()

void QgsMultiRenderChecker::setSizeTolerance ( int  xTolerance,
int  yTolerance 
)
inline

Sets the largest allowable difference in size between the rendered and the expected image.

Parameters
xTolerancex tolerance in pixels
yTolerancey tolerance in pixels

Definition at line 121 of file qgsmultirenderchecker.h.


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