QGIS/python/core/auto_generated/qgsmultirenderchecker.sip.in

/************************************************************************
 * This file has been generated automatically from                      *
 *                                                                      *
 * src/core/qgsmultirenderchecker.h                                     *
 *                                                                      *
 * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
 ************************************************************************/





class QgsMultiRenderChecker
{
%Docstring
This class allows checking rendered images against comparison images.
Its main purpose is for the unit testing framework.

It will either
<ul>
<li>take an externally rendered image (setRenderedImage())</li>
<li>render the image based on provided mapSettings (setMapSettings())</li>
</ul>

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.
<ul>
<li>If there are no subfolders in the control directory, it will assume an image
with the name {controlImage}.png in the control directory itself.</li>

<li>If there are subfolders inside the control directory, it will search for images
with the name {controlImage}.png in every subfolder.</li>
</ul>

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.

.. versionadded:: 2.8
%End

%TypeHeaderCode
#include "qgsmultirenderchecker.h"
%End
  public:

    QgsMultiRenderChecker();
%Docstring
Constructor for QgsMultiRenderChecker.
%End

    virtual ~QgsMultiRenderChecker();

    void setControlName( const QString &name );
%Docstring
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'
%End

    void setControlPathPrefix( const QString &prefix );

    void setRenderedImage( const QString &renderedImagePath );
%Docstring
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

:param renderedImagePath: A path to the rendered image with which control images will be compared
%End

    void setMapSettings( const QgsMapSettings &mapSettings );
%Docstring
Set the map settings to use to render the image

:param mapSettings: The map settings
%End

    void setColorTolerance( unsigned int colorTolerance );
%Docstring
Set tolerance for color components used by runTest()
Default value is 0.

:param colorTolerance: The maximum difference for each color component
                       including alpha to be considered correct.
%End

    void setSizeTolerance( int xTolerance, int yTolerance );
%Docstring
Sets the largest allowable difference in size between the rendered and the expected image.

:param xTolerance: x tolerance in pixels
:param yTolerance: y tolerance in pixels

.. versionadded:: 3.0
%End

    bool runTest( const QString &testName, unsigned int mismatchCount = 0 );
%Docstring
Test using renderer to generate the image to be compared.

:param testName: - to be used as the basis for writing a file to
                 e.g. /tmp/theTestName.png

:param 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
%End

    QString report() const;
%Docstring
Returns a report for this test
%End

    QString controlImagePath() const;
%Docstring
Returns the path to the control images.
%End

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

};

%Feature TESTS
%If (TESTS)


class QgsLayoutChecker : QgsMultiRenderChecker
{
%Docstring
Renders a layout to an image and compares with an expected output

.. versionadded:: 3.0
%End

%TypeHeaderCode
#include "qgsmultirenderchecker.h"
%End
  public:

    QgsLayoutChecker( const QString &testName, QgsLayout *layout );
%Docstring
Constructor for QgsLayoutChecker.
%End

    void setSize( QSize size );
%Docstring
Sets the output (reference) image ``size``.
%End

    bool testLayout( QString &report, int page = 0, int pixelDiff = 0, bool createReferenceImage = false );
%Docstring
Runs a render check on the layout, adding results to the specified ``report``.

The maximum number of allowable pixels differing from the reference image is
specified via the ``pixelDiff`` argument.

A reference image can be created by setting ``createReferenceImage`` to true
in this case the test will always return true.

The page number is specified via ``page``, where 0 corresponds to the first
page in the layout.

Returns false if the rendered layout differs from the expected reference image.
%End

};

%End


/************************************************************************
 * This file has been generated automatically from                      *
 *                                                                      *
 * src/core/qgsmultirenderchecker.h                                     *
 *                                                                      *
 * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
 ************************************************************************/