Raster → Iterators

All examples will use an input raster, as defined here:

// define raster info and load
std::map<std::string, std::string> rinfo;
rinfo["URI"] = "input-raster.tif";
te::rst::Raster* inraster = te::rst::RasterFactory::open(rinfo);
 
// some examples will use the band 0
te::rst::Band* band = inraster->getBand(0);

The Raster iterator implements and iterator to “navigate” over a raster, with a predefined number of bands. Internally, it is composed by a vector of Band Iterator. Iterators are commonly used when the position of the pixel (row, column) is not relevant for a computation.

One example is to compute a histogram of a raster. The following code shows how to use iterators to create a histogram for one band of the raster:

// create one iterator for band 2
std::vector<std::size_t> bands;
bands.push_back(2);
 
te::rst::RasterIterator<double> it = te::rst::RasterIterator<double>::begin(inraster, bands);
te::rst::RasterIterator<double> itend = te::rst::RasterIterator<double>::end(inraster, bands);
 
// create histogram
std::map<double, unsigned long> histogram;
 
double pixel;
while (it != itend)
{
// (*it)[0] is the pixel value in current position, in band 2
  pixel = (*it)[0];
 
// update histogram
  histogram[pixel]++;
 
// change iterator to the next pixel
  ++it;
}

It implements an iterator to “navigate” over a single band (const or not const).

One example is to detect the minimum pixel value of a band:

double minpixel = 256;
 
// create iterators for band 0
te::rst::BandIterator<double> it = te::rst::BandIterator<double>::begin(band);
te::rst::BandIterator<double> itend = te::rst::BandIterator<double>::end(band);
 
while (it != itend)
{
// in this case, *it is the pixel value for band 0
  if (*it < minpixel)
    minpixel = *it;
 
// change iterator to the next pixel
  ++it;
}

The Band Iterator Window implements and iterator to “navigate” over a single band, optimized by a window structure (e.g. 3×3, 5×5, etc). Internally, it stores enough caches of pixel blocks to retrieve the central pixel, and all the pixels from the selected window. Examples include filters, moving windows, morphology, etc.

This example applies the filter “median” for a 5×5 window and stores in the output raster.

// define output raster info and create
std::map<std::string, std::string> orinfo;
orinfo["URI"] = "output-raster.tif";
te::rst::Grid* grid = new te::rst::Grid(*inraster->getGrid());
std::vector<te::rst::BandProperty*> bands;
bands.push_back(new te::rst::BandProperty(0, te::dt::DOUBLE_TYPE, "median in 5x5 window of band 0"));
te::rst::Raster* outraster = te::rst::RasterFactory::make(grid, bands, orinfo);
 
// create iterator for band 0 with a window of 5x5
int W = 5;
int H = 5;
te::rst::BandIteratorWindow<double> it = te::rst::BandIteratorWindow<double>::begin(band, W, H);
te::rst::BandIteratorWindow<double> itend = te::rst::BandIteratorWindow<double>::end(band, W, H);
 
std::set<double> pixel_values_for_median;
std::set<unsigned char>::iterator pixel_it;
while (it != itend)
{
  pixel_values_for_median.clear();
  for (int r = -(H / 2); r <= (H / 2); r++)
    for (int c = -(W / 2); c <= (W / 2); c++)
      pixel_values_for_median.insert(it.getValue(c, r));
 
// the middle position of a set will have the median value
  pixel_it = pixel_values_for_median.begin();
  for (std::size_t i = 0; i < pixel_values_for_median.size() / 2; i++)
    ++pixel_it;
 
  outraster->setValue(it.getColumn(), it.getRow(), *pixel_it);
 
  ++it;
}
 
// clean up output raster to save changes in tif file
delete outraster;

It implements a way to retrieve the pixel's location (and value) inside a band with spatial restriction, in this case a polygon. When using Object-Based Image Analysis (OBIA) most algorithms compute attributes for regions inside a raster. The polygon iterator provides a way to obtain only pixels inside a single region.

The following example shows how to find the average pixel value (mean) inside a region of a band, defined by a polygon.

unsigned int nvalues = 0;
double sum_pixels = 0.0;
double mean = 0.0;
 
// assuming we have a te::gm::Polygon* polygon
te::rst::PolygonIterator<double> it = te::rst::PolygonIterator<double>::begin(band, polygon);
te::rst::PolygonIterator<double> itend = te::rst::PolygonIterator<double>::end(band, polygon);
 
while (it != itend)
{
  sum_pixels += *it;
  nvalues++;
 
  ++it;
}
 
// compute mean value dividing the sum of pixels by the amount of pixels
if (nvalues > 0)
  mean = sum_pixels / nvalues;

It implements a way to retrieve positions inside a band with spatial restriction, in this case a line.

The following code shows how to use the Line iterator to get the pixel values that a line intersects in a band.

std::vector<double> pixels_in_line;
 
// assuming we have a te::gm::Line* line
te::rst::LineIterator<double> it = te::rst::LineIterator<double>::begin(band, line);
te::rst::LineIterator<double> itend = te::rst::LineIterator<double>::end(band, line);
 
while (it != itend)
{
  pixels_in_line.push_back(*it);
 
  ++it;
}

It implements a way to retrieve positions inside a band with spatial restriction, in this case a point set. An example of use is to create a point set with random position, and obtain pixel values for validation purposes.

The following code shows how to use the Point Set iterator to get the pixel values that intersect a vector of points.

std::vector<double> pixels_in_points;
 
// assuming we have a std::vector<te::gm::Point*> points
te::rst::PointSetIterator<double> it = te::rst::PointSetIterator<double>::begin(band, points);
te::rst::PointSetIterator<double> itend = te::rst::PointSetIterator<double>::end(band, points);
 
while (it != itend)
{
  pixels_in_points.push_back(*it);
 
  ++it;
}