.. _example_32:

(32) Draping an image over topography
-------------------------------------

In some cases, it is nice to "drape" an arbitrary image over a
topographic map. We have already seen how to use
:doc:`psimage </psimage>` to plot an image anywhere in
out plot. But here are aim is different, we want to manipulate an image
to shade it and plot it in 3-D over topography. This example was
originally created by Stephan Eickschen for a flyer emphasizing the
historical economical and cultural bond between Brussels, Maastricht and
Bonn. Obviously, the flag of the European Union came to mind as a good
"background".

To avoid adding large files to this example, some steps have been
already done. First we get the EU flag directly from the web and convert
it to a grid with values ranging from 0 to 255, where the higher values
will become yellow and the lower values blue. This use of
:doc:`grdconvert </grdconvert>` requires GDAL support.
:doc:`grdedit </grdedit>` then adds the right grid dimension.

The second step is to reformat the GTOPO30 DEM file to a netCDF grid as
well and then subsample it at the same pixels as the EU flag. We then
illuminate the topography grid so we can use it later to emphasize the
topography. The colors that we will use are those of the proper flag.
Lower values will become blue and the upper values yellow.

The call the :doc:`grdview </grdview>` plots a
topography map of northwest continental Europe, with the flagged draped
over it and with shading to show the little topography there is.
:doc:`pscoast </pscoast>` is used in conjunction with
:doc:`grdtrack </grdtrack>` and :doc:`psxyz </psxyz>` to plot
borders "at altitude". Something similar is done at the end to plot some
symbols and names for cities.

The script produces the plot in the Figure `fig_ex32`. Note
that the PNG image of the flag can be downloaded directly in the call
the :doc:`grdconvert </grdconvert>`, but we have
commented that out in the example because it requires compilation with
GDAL support. You will also see the
:doc:`grdcut </grdcut>` command commented out because we
did not want to store the 58 MB DEM file, whose location is mentioned in the script.

.. literalinclude:: /_verbatim/example_32.txt
   :language: bash

.. _fig_ex32:

.. figure:: /_images/example_32.*
   :width: 500 px
   :align: center

   Draping an image over topography