====== Raster → Iterators ====== All examples will use an input raster, as defined here:


// define raster info and load
std::map 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);

===== Raster Iterator ===== 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 [[wiki:designimplementation:raster:iterators#band_iterator|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 bands;
bands.push_back(2);

te::rst::RasterIterator it = te::rst::RasterIterator::begin(inraster, bands);
te::rst::RasterIterator itend = te::rst::RasterIterator::end(inraster, bands);

// create histogram
std::map 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;
}

===== Band Iterator ===== 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 it = te::rst::BandIterator::begin(band);
te::rst::BandIterator itend = te::rst::BandIterator::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;
}

===== Windowed Iterator ===== The Band Iterator Window implements and iterator to "navigate" over a single band, optimized by a window structure (e.g. 3x3, 5x5, 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 5x5 window and stores in the output raster.


// define output raster info and create
std::map orinfo;
orinfo["URI"] = "output-raster.tif";
te::rst::Grid* grid = new te::rst::Grid(*inraster->getGrid());
std::vector 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 it = te::rst::BandIteratorWindow::begin(band, W, H);
te::rst::BandIteratorWindow itend = te::rst::BandIteratorWindow::end(band, W, H);

std::set pixel_values_for_median;
std::set::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;

===== Polygon Iterator ===== 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. {{:wiki:designimplementation:raster:segmentation_based_spectral_features.png?300|}} 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 it = te::rst::PolygonIterator::begin(band, polygon);
te::rst::PolygonIterator itend = te::rst::PolygonIterator::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;

===== Line Iterator ===== 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 pixels_in_line;

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

===== Point Set Iterator ===== 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 pixels_in_points;

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