.. _example_17:

(17) Images clipped by coastlines
---------------------------------

This example demonstrates how :doc:`pscoast </pscoast>`
can be used to set up clip paths based on coastlines. This approach is
well suited when different gridded data sets are to be merged on a plot
using different color palette files. Merging the files themselves may
not be doable since they may represent different data sets, as we show
in this example. Here, we lay down a color map of the geoid field near
India with :doc:`grdimage </grdimage>`, use
:doc:`pscoast </pscoast>` to set up land clip paths, and
then overlay topography from the ETOPO5 data set with another call to
:doc:`grdimage </grdimage>`. We finally undo the
clippath with a second call to :doc:`pscoast </pscoast>`
with the option **-Q** (Figure [fig:example:sub:`1`\ 7]):

We also plot a color legend on top of the land. So here we basically
have three layers of "paint" stacked on top of each other: the
underlaying geoid map, the land mask, and finally the color legend. This
legend makes clear how :doc:`grd2cpt </grd2cpt>`
distributed the colors over the range: they are not of equal length put
are associated with equal amounts of area in the plot. Since the high
amounts (in red) are not very prevalent, that color spans a long range.

For this image it is appropriate to use the **-I** option in
:doc:`psscale </psscale>` so the legend gets shaded,
similar to the geoid grid. See Appendix [app:M] to learn more about
color palettes and ways to draw color legends.

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

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

   Clipping of images using coastlines.
