In my last tutorial I showed you how to label vector features on the map canvas. Today we will take a brief look at how to add a raster map to the canvas.

QGIS supports displaying more or less any raster formats that are supported by GDAL. More specifically it supports the formats that were compiled into the version of GDAL on your machine. Once a raster layer is loaded you can colourise it if its a greyscale image using a pseudocolour palette that is generated by computing the minimum and maximum values of your layer and then creating 255 equal classbreaks and assigning each break its own colour. Multiband images are also supported by QGIS and you can map individual bands to the red, green and blue (RGB) components of the image. In this tutorial I will focus only on dealing with single band, greyscale images. I used as a basis for this tutorial the project from tutorial 2 (so its worth going over that before reading this tutorial). I've replaced the vector orientated code from tutorial 2 with raster orientated equivalents.

As with my previous tutorials, the entire project can be checked out from the QGIS Subversion repository using the following command:

svn co https://svn.qgis.org/repos/qgis/trunk/code_examples/4_adding_rasters_to_canvas

In the working directory for the tutorial code you will find a number of files including c++ sources, icons and a simple data file under data. There is also the .ui file for the main window.

Note: You will need to edit the .pro file in the above svn directory to match your system.

Raster Specifics

You can browse the code for QgsRasterLayer and related classes using the QGIS source browser. Look in the 'raster' subdirectory. Also for more implementation examples of how to set up the various properties of raster layers, it is worth taking a look at qgsrasterlayerproperties.cpp. Now on with our demo application.... The first thing you should notice is that in 4_adding_rasters_to_canvas.pro I haved added -lqgis_raster to the list of LIBS to be linked to. In mainwindow.cpp you will notice a the include needed to work with rasters:

    #include <qgsrasterlayer.h>

The code that follows sets up the main window and toolbars as covered in previous tutorials. The bit we are really interested in here is:

 
void MainWindow::addLayer()
{
  QFileInfo myRasterFileInfo("data/Abarema_jupunba_projection.tif");
  QgsRasterLayer * mypLayer = new QgsRasterLayer(myRasterFileInfo.filePath(), 
      myRasterFileInfo.completeBaseName());
  if (mypLayer->isValid())
  {
    qDebug("Layer is valid");
  }
  else
  {
    qDebug("Layer is NOT valid");
    return; 
  }
  mypLayer->setColorRampingType(QgsRasterLayer::BLUE_GREEN_RED);
  mypLayer->setDrawingStyle(QgsRasterLayer::SINGLE_BAND_PSEUDO_COLOR);
  std::deque myLayerSet;

  // Add the Vector Layer to the Layer Registry
  QgsMapLayerRegistry::instance()->addMapLayer(mypLayer, TRUE);

  // Add the Layer to the Layer Set
  myLayerSet.push_back(mypLayer->getLayerID());
  mypLayer->setVisible(TRUE);
  // set teh canvas to the extent of our layer
  mpMapCanvas->setExtent(mypLayer->extent());
  // Set the Map Canvas Layer Set
  mpMapCanvas->setLayerSet(myLayerSet);
}

Well that wraps up this tutorial. Adding rasters to your mapcanvas is easy and doesnt take much coding. One thing you should bare in mind is that QGIS does not support on the fly reprojection of rasters so if you are planning to mix rasters from different spatial reference systesm you will probably get undesirable results. If you are planning to add vectors over the raster, add the raster layer to your canvas first and then the vectors. If the vectors are in a different spatial reference system to the raster, these vectors can be reprojected on the fly - which is something I will cover in a future tutorial.

Mac Specific Notes

After building the application bundle (qmake; make) you can copy the spatial reference system database into the bundle to avoid 'cant find resource' type errors:

mkdir -p qgis_example3.app/Contents/MacOS/share/qgis/resources/ 
cp -r /Applications/qgis.app/Contents/MacOS/share/qgis/resources/* \ 
         qgis_example3.app/Contents/MacOS/share/qgis/resources/