:orphan:

.. _example1-5:

===========
Example 1.5
===========

Adding a Raster Layer
---------------------

.. image:: https://demo.mapserver.org/cgi-bin/mapserv?map=/osgeo/mapserver/tutorial/htdocs/example1-5.map&layer=states&layer=states_line&layer=states_label&layer=modis&mode=map

In addition to vector data support (point, lines, polygons, and
annotations), MapServer can also display raster data. Through the use
of GDAL library, MapServer can input and output multiple raster
formats. Whereas in versions prior to 4.x raster input is limited to
single layer, grayscale or indexed color images, recent MapServer
versions support RGB and multispectral (multi-layer) images. This
example shows how to select what layers to display when using
multispectral data.

.. note:: 

     There might be a noticeable performance hit when using RGB and
     multispectral images.

Because MapServer 5.x uses AGG or GD version 2.0.x to generate output
images, it supports RGB (24-bit or true color) output as well. So,
along with 8-bit (indexed color or grayscale) PNG8, you can now also
use PNG (true color) for output. This example uses PNG as
IMAGETYPE.

.. note::

   As with RGB input, there might be a noticeable performance hit when
   using PNG compared to PNG8.

MapServer can actually use GDAL to generate output images as well, but
that's another topic. If you want to know more about it, look at the
:ref:`OUTPUTFORMAT <outputformat>` object in the mapfile reference.

MapFile Structure
#################

This is what the mapfile looks like: :ref:`Example1-5.map <example1-5-map>`

The mapfile structure, by objects, looks like this::

                                               MAP
               LAYER #1-------------LAYER #2----|----LAYER #3--------LAYER #4
            (states_poly)           (modis)       (states_line)   (states_label)
               |                                     |               |
  (land) CLASS-|-CLASS (water)                       |-CLASS         |-CLASS
            |     |                                     |               |
      STYLE-|     |-STYLE                               |-STYLE   STYLE-|-LABEL


When you look at the mapfile, you'll see that the new LAYER object is added below
(after) the state POLYGON layer. Why? MapServer displays layers in reverse order:
last in, first out (LIFO). The first layer defined in the mapfile is drawn at
the bottom of the map.

So, if we have drawn the state POLYGON layer, it would be on the bottom. Since the
raster layer gets drawn on top of it, we won't see it. That's why the first layer
gets the STATUS value of OFF. The state LINE layer is defined below the raster
layer so it gets drawn on top (and you can see it). This is why we separated the
state LINE layer from the state POLYGON layer. Of course the labels get drawn
on top of everything.

MapServer can automatically turn layers on or off based on the status of other
layers (say you want the states polygon layer turned off when the raster layer
is turned on). This is done by using the REQUIRES parameter. Keep this in
mind as you might want to use it once you start creating your own MapServer
applications.

Parameters
##########

Let's have a look at the new parameters introduced in the mapfile:

**IMAGETYPE**
  PNG is the 24-bit or true-color version of the PNG format.  By the
  way, try changing this value to PNG8.  Notice the time it takes to
  generate the image using either formats. In choosing between true
  color and indexed color, take into account the time it takes to
  generate the image.

**SYMBOLSET**
  Points to the path of the symbol definition file. The symbols in
  this file are referenced by the SYMBOL parameter in the :ref:`CLASS
  <class>` object.  It's not really needed at this point but I thought
  I'd throw this here now.  Please refer to the :ref:`Cartographic
  Symbol Reference <sym_construction>` for further information.

**DATA raster/mod09a12003161_ugl_ll_8bit.tif**
  In the newly added LAYER object, the DATA parameter points to a
  GeoTIFF image.  Like vector datasets, MapServer supports multiple
  raster file formats. This support is accomplished through use of the
  GDAL library. For more information on the different raster formats
  supported by MapServer and for general discussion on the use of
  rasters in MapServer, please read the :ref:`Raster Data Reference
  <raster>`.

**TYPE RASTER**
  When using raster data (images) we use the value RASTER for the
  parameter TYPE, as opposed to the POLYGON, LINE, and POINT values
  for vector data and ANNOTATION for label IDs.

**PROCESSING "BANDS=1,2,3"**
  This LAYER object parameter was added in MapServer 4.x. The
  :ref:`PROCESSING <layer>` keyword has many values but in this case
  we are using it to select which bands in a multispectral image to
  display. The values here are strings that will be passed to the GDAL
  library.

**OFFSITE**
  This parameter tells MapServer what pixel values to render as
  background (or ignore). You can get the pixel values using image
  processing or image manipulation programs (i.e. Imagine, Photoshop,
  Gimp).

RGB vs Indexed Color Image
##########################

To compare map creation speed when using RGB image as opposed to indexed color
image, replace the following lines in the mapfile:

.. code-block:: mapfile

  DATA "raster/mod09a12003161_ugl_ll_8bit.tif"
  STATUS DEFAULT
  TYPE RASTER
  PROCESSING "BANDS=1,2,3"
  OFFSITE 71 74 65

with these:

.. code-block:: mapfile


  DATA "raster/mod09a12003161_ugl_ll_idxa.tif"
  STATUS DEFAULT
  TYPE RASTER
  OFFSITE 70 74 66

Also, try changing the IMAGETYPE from PNG to PNG8.

----

:ref:`Back to Example 1.4 <example1-4>` | :ref:`Proceed to Example 1.6 <example1-6>`
