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
• kml_header - used internally
• kml_footer - used internally
• kml_region - used internally
• kml_gauge - used internally
• strip_archive_extensions - strip off things like .tar or .gz

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.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_timespan(t1, t2, event_time=None, tz=None)

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>

System Message: WARNING/2 (/Users/rjl/git/clawpack/clawpack/geoclaw/kmltools.py:docstring of clawpack.geoclaw.kmltools.kml_timespan, line 15)

Definition list ends without a blank line; unexpected unindent.

</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)

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.

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

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

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.