/*! \page create_raster Creating a raster dataset

The code here does not have any warranty. It is recommended that
before using any of this code, you look into it and try to understand
what it does, what input it needs, etc. Do not blindly execute
anything!

This example will create a raster dataset with one band and with cell
value of type Float32. The raster will be stored in GeoTiff format and
it will have ETRS-TM35FIN as the SRS. The coordinates of the upper
left vertex are known and the size of each pixel. Pixels are squares.

\code
use Geo::GDAL;

$driver = 'GTiff';    # name of the GDAL driver
$ext = '.tiff';       # extension for the file
$name = "raster";     # name (without extension) for the new raster
$bands = 1;           # it will have only one band
$datatype = 'Float32';# datatype for the values in pixels
$epsg = 3067;         # SRS as EPSG for the dataset
$width = 200;         # number of pixels in x direction
$height = 100;        # number of pixels in y direction
$minx = 384600;       # x of the left border of leftmost pixel
$dx = 100;            # width of pixels
$maxy = 6672700;      # y of the top border of topmost pixel
$dy = 100;            # height of pixels
$nodata = -1;         # nodata value
@data = ();           # pixel values, stored in this example in an array

$dataset = Geo::GDAL::Driver($driver)->Create($name.$ext, $width, $height, $bands, $datatype);
# Set the transformation matrix from pixels to projection, note minus in front of $dy
$dataset->GeoTransform($minx, $dx, 0, $maxy, 0, -$dy);
$dataset->Projection(Geo::OSR::SpatialReference->new(EPSG=>$epsg)->As('WKT'));
$band = $dataset->Band(1);
$band->NoDataValue($nodata);

# put something into all pixels
# note that x and y here are pixel coordinates, not projection coordinates
# the pixel with biggest value will be bottom right (southeasternmost in this case)
for my $y (0..$height-1) {
    my @row;
    for my $x (0..$width-1) {
        $row[$x] = $x * $y;
    }
    push @data, \@row;
}

# put the data into the GDAL raster
$band->WriteTile(\@data);

# make a hole into the raster
@data = ();
for $y (0..19) {
    for $x (0..29) {
        $data[$y][$x] = $nodata;
    }
}
$band->WriteTile(\@data,10,20);

# the data is flushed to disk when the variable $dataset is destroyed
\endcode

*/
