Iterator for sequentially processing raster cells. More...

#include <qgsrasteriterator.h>

Public Member Functions
	QgsRasterIterator (QgsRasterInterface *input, int tileOverlapPixels=0)
	Constructor for QgsRasterIterator, iterating over the specified input raster source.

qgssize	blockCount () const
	Returns the total number of blocks required to iterate over the input raster.

int	blockCountHeight () const
	Returns the total number of blocks which cover the height of the input raster.

int	blockCountWidth () const
	Returns the total number of blocks which cover the width of the input raster.

const QgsRasterInterface *	input () const
	Returns the input raster interface which is being iterated over.

int	maximumTileHeight () const
	Returns the minimum tile width returned during iteration.

int	maximumTileWidth () const
	Returns the maximum tile width returned during iteration.

bool	next (int bandNumber, int &columns, int &rows, int &topLeftColumn, int &topLeftRow, QgsRectangle &blockExtent)
	Fetches details of the next part of the raster data.

double	progress (int bandNumber) const
	Returns the raster iteration progress as a fraction from 0 to 1.0, for the specified bandNumber.

bool	readNextRasterPart (int bandNumber, int &nCols, int &nRows, QgsRasterBlock **block, int &topLeftCol, int &topLeftRow)
	Fetches next part of raster data, caller takes ownership of the block and caller should delete the block.

bool	readNextRasterPart (int bandNumber, int &nCols, int &nRows, std::unique_ptr< QgsRasterBlock > &block, int &topLeftCol, int &topLeftRow, QgsRectangle blockExtent=nullptr, int tileColumns=nullptr, int tileRows=nullptr, int tileTopLeftColumn=nullptr, int *tileTopLeftRow=nullptr)
	Fetches next part of raster data.

void	setMaximumTileHeight (int h)
	Sets the minimum tile height returned during iteration.

void	setMaximumTileWidth (int w)
	Sets the maximum tile width returned during iteration.

void	setSnapToPixelFactor (int factor)
	Sets the "snap to pixel" factor in pixels.

int	snapToPixelFactor () const
	Returns the current "snap to pixel" factor in pixels.

void	startRasterRead (int bandNumber, qgssize nCols, qgssize nRows, const QgsRectangle &extent, QgsRasterBlockFeedback *feedback=nullptr)
	Start reading of raster band.

void	stopRasterRead (int bandNumber)
	Cancels the raster iteration and resets the iterator.

Static Public Member Functions
static QgsRectangle	subRegion (const QgsRectangle &rasterExtent, int rasterWidth, int rasterHeight, const QgsRectangle &subRegion, int &subRegionWidth, int &subRegionHeight, int &subRegionLeft, int &subRegionTop, int resamplingFactor=1)
	Given an overall raster extent and width and height in pixels, calculates the sub region of the raster covering the specified subRegion.

Static Public Attributes
static const int	DEFAULT_MAXIMUM_TILE_HEIGHT = 2000
	Default maximum tile height.

static const int	DEFAULT_MAXIMUM_TILE_WIDTH = 2000
	Default maximum tile width.

Detailed Description

Iterator for sequentially processing raster cells.

Definition at line 34 of file qgsrasteriterator.h.

Constructor & Destructor Documentation

◆ QgsRasterIterator()

QgsRasterIterator::QgsRasterIterator	(	QgsRasterInterface *	input,
		int	tileOverlapPixels = `0`
	)

Constructor for QgsRasterIterator, iterating over the specified input raster source.

Since QGIS 3.34 the tileOverlapPixels can be used to specify a margin in pixels for retrieving pixels overlapping into neighbor cells.

Definition at line 19 of file qgsrasteriterator.cpp.

Member Function Documentation

◆ blockCount()

qgssize QgsRasterIterator::blockCount ( ) const

inline

Returns the total number of blocks required to iterate over the input raster.

See also: blockCountWidth(); blockCountHeight()

Since: QGIS 3.42

Definition at line 228 of file qgsrasteriterator.h.

◆ blockCountHeight()

int QgsRasterIterator::blockCountHeight ( ) const

inline

Returns the total number of blocks which cover the height of the input raster.

See also: blockCount(); blockCountWidth()

Since: QGIS 3.42

Definition at line 219 of file qgsrasteriterator.h.

◆ blockCountWidth()

int QgsRasterIterator::blockCountWidth ( ) const

inline

Returns the total number of blocks which cover the width of the input raster.

See also: blockCount(); blockCountHeight()

Since: QGIS 3.42

Definition at line 210 of file qgsrasteriterator.h.

◆ input()

const QgsRasterInterface * QgsRasterIterator::input ( ) const

inline

Returns the input raster interface which is being iterated over.

Definition at line 173 of file qgsrasteriterator.h.

◆ maximumTileHeight()

int QgsRasterIterator::maximumTileHeight ( ) const

inline

Returns the minimum tile width returned during iteration.

See also: setMaximumTileHeight(); maximumTileWidth()

Definition at line 201 of file qgsrasteriterator.h.

◆ maximumTileWidth()

int QgsRasterIterator::maximumTileWidth ( ) const

inline

Returns the maximum tile width returned during iteration.

See also: setMaximumTileWidth(); maximumTileHeight()

Definition at line 187 of file qgsrasteriterator.h.

◆ next()

bool QgsRasterIterator::next	(	int	bandNumber,
		int &	columns,
		int &	rows,
		int &	topLeftColumn,
		int &	topLeftRow,
		QgsRectangle &	blockExtent
	)

Fetches details of the next part of the raster data.

This method does NOT actually fetch the raster data itself, rather it calculates and iterates over the details of the raster alone.

It's useful for iterating over several layers using a target "reference" layer. E.g. summing the pixels in n rasters whilst aligning the result to a reference layer which is not being summed.

Note that calling this method also advances the iterator, just like calling readNextRasterPart().

Parameters

bandNumber	band to read
columns	number of columns on output device
rows	number of rows on output device
topLeftColumn	top left column
topLeftRow	top left row
blockExtent	exact extent of returned raster block

Returns: false if the last part was already returned

Since: QGIS 3.6

Definition at line 113 of file qgsrasteriterator.cpp.

◆ progress()

double QgsRasterIterator::progress ( int bandNumber ) const

Returns the raster iteration progress as a fraction from 0 to 1.0, for the specified bandNumber.

Since: QGIS 3.42

Definition at line 256 of file qgsrasteriterator.cpp.

◆ readNextRasterPart() [1/2]

bool QgsRasterIterator::readNextRasterPart	(	int	bandNumber,
		int &	nCols,
		int &	nRows,
		QgsRasterBlock **	block,
		int &	topLeftCol,
		int &	topLeftRow
	)

Fetches next part of raster data, caller takes ownership of the block and caller should delete the block.

Parameters

bandNumber	band to read
nCols	number of columns on output device
nRows	number of rows on output device
block	address of block pointer
topLeftCol	top left column
topLeftRow	top left row

Returns: false if the last part was already returned

Definition at line 122 of file qgsrasteriterator.cpp.

◆ readNextRasterPart() [2/2]

bool QgsRasterIterator::readNextRasterPart	(	int	bandNumber,
		int &	nCols,
		int &	nRows,
		std::unique_ptr< QgsRasterBlock > &	block,
		int &	topLeftCol,
		int &	topLeftRow,
		QgsRectangle *	blockExtent = `nullptr`,
		int *	tileColumns = `nullptr`,
		int *	tileRows = `nullptr`,
		int *	tileTopLeftColumn = `nullptr`,
		int *	tileTopLeftRow = `nullptr`
	)

Fetches next part of raster data.

Parameters

bandNumber	band to read
nCols	number of columns on output device
nRows	number of rows on output device
block	address of block pointer
topLeftCol	top left column
topLeftRow	top left row
blockExtent	optional storage for exact extent of returned raster block
tileColumns	optional storage for number of columns in the iterated tile (excluding any tile overlap pixels)
tileRows	optional storage for number of rows in the iterated tile (excluding any tile overlap pixels)
tileTopLeftColumn	optional storage for the top left column in the iterated tile (excluding any tile overlap pixels)
tileTopLeftRow	optional storage for the top left row in the iterated tile (excluding any tile overlap pixels)

Returns: false if the last part was already returned

Note: Not available in Python bindings

Since: QGIS 3.2

Definition at line 135 of file qgsrasteriterator.cpp.

◆ setMaximumTileHeight()

void QgsRasterIterator::setMaximumTileHeight ( int h )

inline

Sets the minimum tile height returned during iteration.

See also: maximumTileHeight(); setMaximumTileWidth()

Definition at line 194 of file qgsrasteriterator.h.

◆ setMaximumTileWidth()

void QgsRasterIterator::setMaximumTileWidth ( int w )

inline

Sets the maximum tile width returned during iteration.

See also: maximumTileWidth(); setMaximumTileHeight()

Definition at line 180 of file qgsrasteriterator.h.

◆ setSnapToPixelFactor()

void QgsRasterIterator::setSnapToPixelFactor ( int factor )

inline

Sets the "snap to pixel" factor in pixels.

When set to a value greater than 1, the raster blocks will be snapped to boundaries matching exact multiples of this factor.

Set to 1 to disable this behavior (default).

Warning: When the "snap to pixel" factor is set, the iterated portion of the raster may not cover the entire input raster extent. A band of pixels on the right and bottom, with size at most of snap to pixel factor - 1, may be skipped if they cannot be snapped exactly to the factor.

See also: snapToPixelFactor()

Since: QGIS 3.42

Definition at line 60 of file qgsrasteriterator.h.

◆ snapToPixelFactor()

int QgsRasterIterator::snapToPixelFactor ( ) const

inline

Returns the current "snap to pixel" factor in pixels.

Warning: When the "snap to pixel" factor is set, the iterated portion of the raster may not cover the entire input raster extent. A band of pixels on the right and bottom, with size at most of snap to pixel factor - 1, may be skipped if they cannot be snapped exactly to the factor.

See also: setSnapToPixelFactor()

Since: QGIS 3.42

Definition at line 72 of file qgsrasteriterator.h.

◆ startRasterRead()

void QgsRasterIterator::startRasterRead	(	int	bandNumber,
		qgssize	nCols,
		qgssize	nRows,
		const QgsRectangle &	extent,
		QgsRasterBlockFeedback *	feedback = `nullptr`
	)

Start reading of raster band.

Raster data can then be retrieved by calling readNextRasterPart until it returns false.

Parameters

bandNumber	number of raster band to read
nCols	number of columns
nRows	number of rows
extent	area to read
feedback	optional raster feedback object for cancellation/preview. Added in QGIS 3.0.

Definition at line 88 of file qgsrasteriterator.cpp.

◆ stopRasterRead()

void QgsRasterIterator::stopRasterRead ( int bandNumber )

Cancels the raster iteration and resets the iterator.

Definition at line 251 of file qgsrasteriterator.cpp.

◆ subRegion()

QgsRectangle QgsRasterIterator::subRegion	(	const QgsRectangle &	rasterExtent,
		int	rasterWidth,
		int	rasterHeight,
		const QgsRectangle &	subRegion,
		int &	subRegionWidth,
		int &	subRegionHeight,
		int &	subRegionLeft,
		int &	subRegionTop,
		int	resamplingFactor = `1`
	)

static

Given an overall raster extent and width and height in pixels, calculates the sub region of the raster covering the specified subRegion.

Parameters

rasterExtent	overall raster extent
rasterWidth	overall raster width
rasterHeight	overall raster height
subRegion	desired sub region extent
subRegionWidth	width in pixels of sub region
subRegionHeight	height in pixels of sub region
subRegionLeft	starting column of left side of sub region
subRegionTop	starting row of top side of sub region
resamplingFactor	optional resampling factor to snap boundaries to. When specified the calculated subregion will always be shrunk to snap to the pixel boundaries. (since QGIS 3.42)

Returns: sub region geographic extent, snapped to exact pixel boundaries

Since: QGIS 3.26

Definition at line 37 of file qgsrasteriterator.cpp.

Member Data Documentation

◆ DEFAULT_MAXIMUM_TILE_HEIGHT

const int QgsRasterIterator::DEFAULT_MAXIMUM_TILE_HEIGHT = 2000

static

Default maximum tile height.

Definition at line 241 of file qgsrasteriterator.h.

◆ DEFAULT_MAXIMUM_TILE_WIDTH

const int QgsRasterIterator::DEFAULT_MAXIMUM_TILE_WIDTH = 2000

static

Default maximum tile width.

Definition at line 238 of file qgsrasteriterator.h.

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

/build/qgis-3.41.0+git20241225+af5edcb665c+99sid/src/core/raster/qgsrasteriterator.h
/build/qgis-3.41.0+git20241225+af5edcb665c+99sid/src/core/raster/qgsrasteriterator.cpp

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ QgsRasterIterator()

Member Function Documentation

◆ blockCount()

◆ blockCountHeight()

◆ blockCountWidth()

◆ input()

◆ maximumTileHeight()

◆ maximumTileWidth()

◆ next()

◆ progress()

◆ readNextRasterPart() [1/2]

◆ readNextRasterPart() [2/2]

◆ setMaximumTileHeight()

◆ setMaximumTileWidth()

◆ setSnapToPixelFactor()

◆ snapToPixelFactor()

◆ startRasterRead()

◆ stopRasterRead()

◆ subRegion()

Member Data Documentation

◆ DEFAULT_MAXIMUM_TILE_HEIGHT

◆ DEFAULT_MAXIMUM_TILE_WIDTH