kmltools module of utility functions¶
Warning
This describes new tools to be 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
kml_header - used internally
kml_footer - used internally
kml_region - used internally
kml_gauge - used internally
kml_png - 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.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.
