Class: QgsRasterIterator

Iterator for sequentially processing raster cells.

Methods

blockCount	Returns the total number of blocks required to iterate over the input raster.
blockCountHeight	Returns the total number of blocks which cover the height of the input raster.
blockCountWidth	Returns the total number of blocks which cover the width of the input raster.
input	Returns the input raster interface which is being iterated over.
maximumTileHeight	Returns the minimum tile width returned during iteration.
maximumTileWidth	Returns the maximum tile width returned during iteration.
next	Fetches details of the next part of the raster data.
progress	Returns the raster iteration progress as a fraction from 0 to 1.0, for the specified bandNumber.
readNextRasterPart	Fetches next part of raster data, caller takes ownership of the block and caller should delete the block.
setMaximumTileHeight	Sets the minimum tile height returned during iteration.
setMaximumTileWidth	Sets the maximum tile width returned during iteration.
setSnapToPixelFactor	Sets the "snap to pixel" factor in pixels.
snapToPixelFactor	Returns the current "snap to pixel" factor in pixels.
startRasterRead	Start reading of raster band.
stopRasterRead	Cancels the raster iteration and resets the iterator.

Static Methods

subRegion

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

Attributes

DEFAULT_MAXIMUM_TILE_HEIGHT	Default maximum tile height
DEFAULT_MAXIMUM_TILE_WIDTH	Default maximum tile width

class qgis.core.QgsRasterIterator

Bases: object

__init__(input: QgsRasterInterface | None, tileOverlapPixels: int = 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.

Parameters:

• input (Optional[QgsRasterInterface])

• tileOverlapPixels (int = 0)

__init__(a0: QgsRasterIterator)

Parameters:

a0 (QgsRasterIterator)

DEFAULT_MAXIMUM_TILE_HEIGHT: int = 2000

Default maximum tile height

DEFAULT_MAXIMUM_TILE_WIDTH: int = 2000

Default maximum tile width

blockCount(self) → int

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

See also

blockCountWidth()

See also

blockCountHeight()

Added in version 3.42.

Return type:

int

blockCountHeight(self) → int

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

See also

blockCount()

See also

blockCountWidth()

Added in version 3.42.

Return type:

int

blockCountWidth(self) → int

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

See also

blockCount()

See also

blockCountHeight()

Added in version 3.42.

Return type:

int

input(self) → QgsRasterInterface | None

Returns the input raster interface which is being iterated over.

Return type:

Optional[QgsRasterInterface]

maximumTileHeight(self) → int

Returns the minimum tile width returned during iteration.

See also

setMaximumTileHeight()

See also

maximumTileWidth()

Return type:

int

maximumTileWidth(self) → int

Returns the maximum tile width returned during iteration.

See also

setMaximumTileWidth()

See also

maximumTileHeight()

Return type:

int

next(self, bandNumber: int)

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 (int) -> (bool) – band to read

Returns:

• False if the last part was already returned

• 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

Added in version 3.6.

progress(self, bandNumber: int) → float

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

Added in version 3.42.

Parameters:

bandNumber (int)

Return type:

float

readNextRasterPart(self, bandNumber: int)

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

Parameters:

• bandNumber (int) -> (bool) – 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

setMaximumTileHeight(self, h: int)

Sets the minimum tile height returned during iteration.

See also

maximumTileHeight()

See also

setMaximumTileWidth()

Parameters:

h (int)

setMaximumTileWidth(self, w: int)

Sets the maximum tile width returned during iteration.

See also

maximumTileWidth()

See also

setMaximumTileHeight()

Parameters:

w (int)

setSnapToPixelFactor(self, factor: int)

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()

Added in version 3.42.

Parameters:

factor (int)

snapToPixelFactor(self) → int

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()

Added in version 3.42.

Return type:

int

startRasterRead(self, bandNumber: int, nCols: int, nRows: int, extent: QgsRectangle, feedback: QgsRasterBlockFeedback | None = None)

Start reading of raster band. Raster data can then be retrieved by calling readNextRasterPart until it returns False.

Parameters:

• bandNumber (int) – number of raster band to read

• nCols (int) – number of columns

• nRows (int) – number of rows

• extent (QgsRectangle) – area to read

• feedback (Optional[QgsRasterBlockFeedback] = None) – optional raster feedback object for cancellation/preview. Added in QGIS 3.0.

stopRasterRead(self, bandNumber: int)

Cancels the raster iteration and resets the iterator.

Parameters:

bandNumber (int)

static subRegion(rasterExtent: QgsRectangle, rasterWidth: int, rasterHeight: int, subRegion: QgsRectangle, resamplingFactor: int = 1)

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

Parameters:

• rasterExtent (QgsRectangle) – overall raster extent

• rasterWidth (int) – overall raster width

• rasterHeight (int) – overall raster height

• subRegion (QgsRectangle) – desired sub region extent

• resamplingFactor (int = 1) -> (QgsRectangle) – 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

• 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

Added in version 3.26.