kmltools module of utility functions

This describes new tools added in Clawpack 5.2.1.

Documentation auto-generated from the module docstrings

kmltools module: $CLAW/geoclaw/src/python/geoclaw/kmltools.py

Tools to make kml files to overlay on Google Earth. Note that color is in KML format, BGR with 2 hex digits for each, e.g.

FF0000 is blue, 00FF00 is green, 0000FF is red, 00FF00 is yellow.

Actually it’s an 8 hex digit number, where the first two digits are transparency, but in this module these default to ‘FF’ (but you can specify the full 8 digits if you want it transparent).

Functions:

  • deg2dms - convert decimal degrees to (degrees, minutes, seconds)

  • regions2kml - create a kml outline for each regions specified in setrun

  • box2kml - create a kml outline from a rectangular box

  • quad2kml - create a kml outline for an arbitrary quadrilateral

  • poly2kml - create a kml outline for an arbitrary polygon

  • line2kml - create a kml line connecting 2 points

  • gauges2kml - create a kml marker for each gauge specified in setrun

  • topo2kml - create a kml outline for each topo grid specified in setrun

  • dtopo2kml - create a kml outline for each dtopo grid specified in setrun

  • fgmax2kml - create a kml outline for each fgmax grid specified in setrun

  • fgout2kml - create a kml outline for each fgout grid specified in setrun

  • make_input_data_kmls - make kml files for many things specified in setrun

  • pcolorcells_for_kml - version of pcolormesh with appropriate dpi and size

  • png2kml - create kml file wrapping a png figure to be viewed on GE

  • kml_build_colorbar - create a colorbar to display on GE

  • topo2kmz - create kmz file showing onshore and offshore topography

  • transect2kml - create kml file showing a set of points on a transect

  • kml_header - used internally

  • kml_footer - used internally

  • kml_region - used internally

  • kml_gauge - used internally

  • kml_png - used internally

  • kml_cb - used internally

clawpack.geoclaw.kmltools.box2kml(xy, fname=None, name='box', color='FF0000', width=3, verbose=True)

Make a KML box with default color blue.

Inputs:
  • xy a tuple ((x1,x2),(y1,y2)) (preferred)

    or (x1,x2,y1,y2) (for backward compatibility)

  • fname (str) name of resulting kml file

  • name (str) name to appear in box on Google Earth

  • color (str) Color in format aabbggrr

  • width (str) line width

  • verbose (bool) - If True, print out info

clawpack.geoclaw.kmltools.deg2dms(dy)

Convert decimal degrees to tuple (degrees, minutes, seconds)

clawpack.geoclaw.kmltools.dtopo2kml(dtopo_file_name, dtopo_type, color='8888FF')

Create a kml file putting a box around the region covered by a dtopofile. Color is pink by default.

clawpack.geoclaw.kmltools.f2s(x, num_digits=6)

Convert float to string in fixed point notation with at most num_digits digits of precision and trailing zeros removed, for printing nicely in kml description boxes.

clawpack.geoclaw.kmltools.fgmax2kml(rundata=None, fname='fgmax_grids.kml', verbose=True, combined=False)

Create a KML box for each fgmax grid specified for a GeoClaw run.

Inputs:

  • rundata - an object of class ClawRunData or None

    If rundata==None, try to create based on executing function setrun from the setrun.py file in the current directory.

  • fname (str) - resulting kml file.

  • verbose (bool) - If True, print out info about each region found

  • combined (bool) - If True, combine into single kml file with name given by fname. NOT YET IMPLEMENTED. If False, fname is ignored and individual files are created for each fgmax grid.

clawpack.geoclaw.kmltools.fgout2kml(rundata=None, fname='fgout_grids.kml', verbose=True, combined=False)

Create a KML box for each fgout grid specified for a GeoClaw run.

Inputs:

  • rundata - an object of class ClawRunData or None

    If rundata==None, try to create based on executing function setrun from the setrun.py file in the current directory.

  • fname (str) - resulting kml file.

  • verbose (bool) - If True, print out info about each region found

  • combined (bool) - If True, combine into single kml file with name given by fname. NOT YET IMPLEMENTED. If False, fname is ignored and individual files are created for each fgout grid.

clawpack.geoclaw.kmltools.gauges2kml(rundata=None, fname='gauges.kml', verbose=True)

Create a KML marker for each gauge specified for a GeoClaw run.

Inputs:

  • rundata - an object of class ClawRunData or None

    If rundata==None, try to create based on executing function setrun from the setrun.py file in the current directory.

  • fname (str) - resulting kml file.

  • verbose (bool) - If True, print out info about each region found

Example:
>>> from clawpack.geoclaw import kmltools
>>> kmltools.gauges2kml()

is equivalent to:

>>> from clawpack.geoclaw import kmltools
>>> from setrun import setrun
>>> rundata = setrun()
>>> kmltools.gauges2kml(rundata)

By default this creates a file named gauges.kml that can be opened in Google Earth.

clawpack.geoclaw.kmltools.kml_build_colorbar(cb_filename, cmap, cmin=None, cmax=None, norm=None, label=None, title=None, extend='neither', close_figs=True)

Make a png file with a colorbar corresponding to cmap, norm. cmin, cmax are used only if nrm is not provided.

clawpack.geoclaw.kmltools.kml_cb(mapping)

Create text for a colorbar png file overlay

clawpack.geoclaw.kmltools.kml_png(mapping)

Create text for a png file overlay

clawpack.geoclaw.kmltools.kml_timespan(t1, t2, event_time=None, tz=None, tscale=1)

Create time strings necessary for sliders in Google Earth. The time span will cover time [t1,t2], with the start of the event given by event_time.

[t1,t2] : time span,

event_time : Start of event in UTC : [Y,M,D,H,M,S], e.g. [2010,2,27,3,34,0] tz : time zone offset to UTC. e.g. +3 for Chile; -9 for Japan.

Time span element looks like

<TimeSpan>
  <begin>2010-02-27T06:34:00+03:00</begin>
  <end>2010-02-27T07:04:00+03:00</end>
</TimeSpan>

As for how well this handles Daylight Savings time, here is what the documentation on the Python ‘time’ module has to say :

“DST is Daylight Saving Time, an adjustment of the timezone by (usually) one hour during part of the year. DST rules are magic (determined by local law) and can change from year to year. The C library has a table containing the local rules (often it is read from a system file for flexibility) and is the only source of True Wisdom in this respect.”

clawpack.geoclaw.kmltools.line2kml(xy, fname='line.kml', name='line', color='00FFFF', width=3, verbose=True)

Make a KML line with default color yellow.

Inputs:
  • xy a tuple ((x1,x2),(y1,y2)) (preferred)

    or (x1,x2,y1,y2) (for backward compatibility)

  • fname (str) name of resulting kml file

  • name (str) name to appear on line on Google Earth

  • color (str) Color in format aabbggrr

  • width (str) line width

  • verbose (bool) - If True, print out info

clawpack.geoclaw.kmltools.make_input_data_kmls(rundata=None, combined=False)

Produce kml files for the computational domain, all gauges and regions specified, and all topo and dtopo files specified in rundata. This can be used, e.g. by adding the lines

from clawpack.geoclaw import kmltools kmltools.make_input_data_kmls(rundata)

to the end of a setrun.py file so that make data will generate all kml files in addition to the *.data files.

Or set rundata==None, in which case it will try to generate rundata based on executing function setrun from the setrun.py file in the current directory.

clawpack.geoclaw.kmltools.pcolorcells_for_kml(X, Y, Z, png_filename=None, dpc=2, max_inches=15.0, verbose=True, **kwargs)

Wraps pcolormesh in a way that a png file is created that can be viewed on Google Earth with proper alignment and with sharp grid cell edges. Works if X,Y are cell centers or edges, and X,Y can be 2d or 1d arrays.

X,Y,Z is the data to be plotted. It is assumed to be finite volume data where Z[i,j] is a constant value over a grid cell.

Internally x,y are defined as 1d arrays since it is assumed the grids are Cartesian.

If the length of the 1d arrays x and y match the dimensions of Z then these are assumed to be cell center values. In this case the arrays are expanded by one to obtain x_edge, y_edge as edge values, as needed for proper alignment.

If the length of x,y is already one greater than the corresponding dimension of Z, then it is assumed that these are already edge values.

If png_filename is not None then a png file is written with appropriate dpi.

dpc is the desired “dots per cell”, how many pixels to allot to each to each grid cell. This should be an integer to avoid interpolation between cells that smears out the cell boundaries in the png file. Increasing this will give sharper boundaries but also larger files that load more slowly.

max_inches is the desired size of the longer edge of the figure created. This value is not very important unless you want to view the png file on a screen outside of Google Earth. Internally the dimensions of the figure x_inches and y_inches are determined to be consistent with the value dpc specified and a reasonable value of dpi for the png file, as described below.

Internally the value dpi (dots per inch) for the png file is determined so that it is at least 16 and so that:

dpi * x_inches = dcp * x_cells dpi * y_inches = dcp * y_cells

where x_cells, y_cells are the number of cells in each direction.

kwargs are passed to pcolormesh, e.g. cmap and norm are generally specified.

This function returns fig, ax, png_extent, kml_dpi so the user can further annotate the figure befor saving it as a png file, which should then be done with:

plt.savefig(png_filename, transparent=True, dpi=kml_dpi)

The png_extent is needed in construcing a kml file to display the png file on Google Earth, e.g. using the function png2kml in this module.

clawpack.geoclaw.kmltools.png2kml(extent, png_files, png_names=None, name='png_files', fname=None, radio_style=False, cb_files=None, cb_names=None, cb_xfracs=None, cb_yfracs=None, verbose=True)

Create a kml file fname linking overlays for each png file in png_files.

extent is [x1,x2,y1,y2] specifying where image should be overlaid.

png_names, if present, will give the name for each image for the Google Earth menu.

If radio_style is True, set radio buttons so only one can be shown at a time, useful for combining plots of different quantities in same file.

clawpack.geoclaw.kmltools.poly2kml(xy, fname=None, name='poly', color='00FF00', width=3, verbose=True, max_vertices_in_description=20)

Make a KML polygon with default color blue.

Inputs:

  • xy a tuple (x,y) where x and y are lists of vertices

  • fname (str) name of resulting kml file

  • name (str) name to appear in box on Google Earth

  • color (str) Color in format aabbggrr

  • width (str) line width

  • verbose (bool) - If True, print out info

  • max_vertices_in_description (int) - if more than this number of vertices, only list number in description box, not all vertices

clawpack.geoclaw.kmltools.quad2kml(xy, fname=None, name='quad', color='FF0000', width=3, verbose=True)

Make a KML quadrilateral with default color blue.

Inputs:
  • xy a tuple ((x1,x2,x3,x4),(y1,y2,y3,y4)) (preferred)

    or (x1,x2,y1,y2,x3,y3,x4,y4) (for backward compatibility)

  • fname (str) name of resulting kml file

  • name (str) name to appear in box on Google Earth

  • color (str) Color in format aabbggrr

  • width (str) line width

  • verbose (bool) - If True, print out info

clawpack.geoclaw.kmltools.regions2kml(rundata=None, fname='regions.kml', verbose=True, combined=True)

Create a KML box for each AMR region specified for a GeoClaw run.

Inputs:

  • rundata - an object of class ClawRunData or None

    If rundata==None, try to create based on executing function setrun from the setrun.py file in the current directory.

  • fname (str) - resulting kml file.

  • verbose (bool) - If True, print out info about each region found

  • combined (bool) - If True, combine into single kml file with name given by fname. This is the default. If False, fname is ignored and individual files are created for each region with names are Domain.kml, Region00.kml, etc. These will show up separately in GoogleEarth so they can be turned on or off individually.

First create a box for the entire domain (in red) and then a box for each region (in white).

Example:
>>> from clawpack.geoclaw import kmltools
>>> kmltools.regions2kml()

is equivalent to:

>>> from clawpack.geoclaw import kmltools
>>> from setrun import setrun
>>> rundata = setrun()
>>> kmltools.regions2kml(rundata)

By default this creates a file named regions.kml that can be opened in Google Earth.

clawpack.geoclaw.kmltools.topo2kml(topo_file_name, topo_type, color='00FF00')

Create a kml file putting a box around the region covered by a topofile. Color is green by default.

clawpack.geoclaw.kmltools.topo2kmz(topo, zlim=(-20, 20), mask_outside_zlim=True, sea_level=0.0, name='topo', force_dry=None, close_figs=True)

Create kmz file showing onshore and offshore topography as separate layers. Currently not very flexible but is useful in quickly creating kmz files to open on Google Earth showing the onshore topography and offshore bathymetry as two separate layers. Constant colors on rectangular grid cells should be properly rendered to ease exploration of DEMs. A colorbar png file is also created and included in the kmz file.

Input:

  • topo should be a topotools.Topography object,

  • zlim is the elevation z limits for choosing the color map

  • mask_outside_zlim if True, suppress plotting outsize zlim

  • sea_level is the break between water and land colors

  • name is used in the kml menu and file name

  • force_dry is currently not used

  • close_figs to close the pyplot figures after making png files

Future:

If force_dry is an array of the same shape as topo.Z then another png and kml file are created for land that is below sea_level but where force_dry = True.

clawpack.geoclaw.kmltools.transect2kml(xtrans, ytrans, fname='transect.kml')

Create a kml file for points with long,lat specified by xtrans,ytrans. Label each point with number and coordinates. Adjust longitudes in coordinates so they are all between -180 and 180 to display properly in Google Earth (but labels are original values).