.. _geotools:

Geotools Python module
======================

This module contains
some tools for manipulating and plotting `topo` and `dtopo` files
(prescribing topography, bathymetry, and changes to topography such as
earthquake sources).

Clawpack 4.6 (on the VM) contains some tools in the directories
`$CLAW/python/pyclaw/geotools` and
`$CLAW/python/pyclaw/plotting/geoplot.py`.
(Note thate `$CLAW` is the environment variable that should be set to the
main Clawpack directory.)

Some improved versions of these routines will be used for the summer school.

*Tools still under development*, but if you want to try using them, download
`geotools2.tar <../geotools2.tar>`_
into the directory `$CLAW/python` and in that directory, do::

    $ tar -xf geotools2.tar

to create the `geotools2` directory.


Plotting topo data
------------------

For some information on acquiring topo data and the different file formats
supported in GeoClaw, see
`Topography data documentation <http://depts.washington.edu/clawpack/users-4.6/topo.html>`_.

See also the `Quick start guide
<http://depts.washington.edu/clawpack/users-4.6/quick_tsunami.html>`_
for tsunami modeling, but some of the new plotting tools in `geotools2`
may work better.

As an example, try the following::

    $ cd $CLAW/python/pyclaw/geotools2
    $ python test_topoplots_tohoku.py

This should reads in two topo files (at resolution 4 minutes and over a
smaller region at 1 minute) and plots the topo together.
Here is the code:

.. literalinclude:: ../geotools2/test_topoplots_tohoku.py
   :language: python
   :linenos:

It should create a figure that looks like this:

.. image :: images/TohokuTopo.png
   :width: 15cm

If you want to be able to zoom in on the figure, it is better to run this
code in Ipython, a nice interactive shell for Python::

    $ ipython --pylab
    In[1]: run test_topoplots_tohoku.py

If you want to manipulate the topo data, e.g. to plot something different,
you might want to read it in using `topotools.topofile2griddata`, e.g. as
done in this example (found in `test_topotools_tohoku.py`):

.. literalinclude:: ../geotools2/test_topotools_tohoku.py
   :language: python
   :linenos:

Run this code in IPython and it should produce a plot like this:

.. image :: images/TohokuTopo2.png
   :width: 15cm

Here's a code that plots contour lines from two different *topo* file to
make it easier to see if the bathymetry matches up well at the edge of the
finer grid (found in `test_compare_contours.py`):

.. literalinclude:: ../geotools2/test_compare_contours.py
   :language: python
   :linenos:

Plot in IPython and zoom in to see how well it matches up.  Of course you
might need to plot different contour levels if you want to see how things
look near the coast, for example.