====== Raster → Basic I/O ======

Each raster is composed by one or more bands, and each band has its own pixel values. If the pixel positions are not necessary when accessing the raster, the [[wiki:designimplementation:raster:iterators#raster_iterator|Iterators]] can be used instead.

When the user needs to know basic information about one raster, the method //toString()// can be used:

<code cpp>
// load the input image
std::map<std::string, std::string> rinfo;
rinfo["URI"] = "input.tif";
te::rst::Raster* rin = te::rst::RasterFactory::open(rinfo);

// display information about raster
std::cout << rin->toString();

// clean up
delete rin;
</code>

The output will be:

<code>
Raster Name......: input.tif
Number of Columns: 369
Number of Rows...: 351
Number of Bands..: 3
SRID.............: 29181
Resolution in X..: 20
Resolution in Y..: 20
Extent UR........: 777957, 7.37011e+06
Extent LL........: 770597, 7.36311e+06

Band: 0 
  Min Values...: (15,0)
  Max Values...: (255,0)
  Mean Values..: (134.406,0)
  Std Values...: (46.0585,0)
  Gain values..: (1,0)
  Offset values: (0,0)

Band: 1 
  Min Values...: (61,0)
  Max Values...: (255,0)
  Mean Values..: (209.62,0)
  Std Values...: (29.6003,0)
  Gain values..: (1,0)
  Offset values: (0,0)

Band: 2 
  Min Values...: (10,0)
  Max Values...: (255,0)
  Mean Values..: (148.682,0)
  Std Values...: (36.1113,0)
  Gain values..: (1,0)
  Offset values: (0,0)
</code>

===== Pixel access =====

The following methods can be used to retrieve the pixel values from a specific band:

<code cpp>
double pixel; // when using complex pixels, can use std::complex<double> pixel;
const unsigned int line = 10,
                   column = 20;
                   band = 3;

te::rst::Raster* myraster = ...

// using the raster interface
myraster->getValue(line, column, pixel, band);

// using the [] operator
myraster[band]->getValue(line, column, pixel);

// using the band interface
te::rst::Band* myband = myraster->getBand(band);

myband->getValue(line, column, pixel);

// using a vector of pixel values from the same line/column
std::vector<double> pixels;

myraster->getValues(line, column, pixels);

pixel = pixels[band];
</code>

To change values in a raster, the a similar method is used, however the raster access policy must be set to //WAccess// or //RWAccess//.

<code cpp>
const double pixel = 125.0; // when using complex pixels, can use std::complex<double> pixel(125.0, 23.5);
const unsigned int line = 10,
                   column = 20;
                   band = 3;

te::rst::Raster* myraster = ...

// using the raster interface
myraster->setValue(line, column, pixel, band);

// using the [] operator
myraster[band]->setValue(line, column, pixel);

// using the band interface
te::rst::Band* myband = myraster->getBand(band);

myband->setValue(line, column, pixel);

// using a vector of pixel values from the same line/column
std::vector<double> pixels(myraster->getNumberOfBands());

pixels[band] = pixel;

myraster->setValues(line, column, pixels);
</code>

===== Block Access =====

Internally, each band is accessed by blocks of contiguous pixels. When the user needs to have a faster access to pixel values, this option can be used. The following example shows how to copy a block of pixels from one input band to an output band, assuming both bands have the same block configuration and data types.

<code c++>
void te::rst::Copy(const te::rst::Band& bin, te::rst::Band& bout)
{
// create a block of pixels using the method getBlockSize() from the band
  unsigned char* buffer = new unsigned char[bin.getBlockSize()];

// the number of blocks in both directions (x and y)
  const int nblocksx = bin.getProperty()->m_nblocksx,
            nblocksy = bin.getProperty()->m_nblocksy;

// use methods read/write to copy the entire blocks
  for(int y = 0; y < nblocksy; ++y)
    for(int x = 0; x < nblocksx; ++x)
    {
      bin.read(x, y, buffer);
      bout.write(x, y, buffer);
    }

//clean up
  delete [] buffer;
}
</code>