.. _googleearth_plotting: ******************************************* Visualizing GeoClaw results in Google Earth ******************************************* .. _Google Earth: http://www.google.com/earth The `Google Earth`_ browser is a powerful visualization tool for viewing geo-located data. The VisClaw visualization suite includes tools that will produce plots and associated KMZ files needed for easy browsing of your GeoClaw simulation results in Google Earth. GeoClaw tsunami simulations are particularly appropriate for the Google Earth platform in that land topography, ocean bathymetry and wave disturbances created by tsunamis or other inundationevents can all be viewed simultaneously. The Google Earth browser is not a fully functional GIS tool, and so while the simulations may look very realistic, one should not base critical decisions on conclusions drawn from the Google Earth visualization alone. Nevertheless, these realistic visualizations are useful for setting up simulations and communicating your results. Basic requirements ================== .. _lxml: http://pypi.python.org/pypi/lxml/3.4.0 .. _GDAL: http://www.gdal.org .. _pykml: http://pythonhosted.org/pykml/ To get started, you will need to install the Python packages `lxml`_ and `pykml`_. These libraries can be easily installed through Python package managers *PIP* and *conda*:: % conda install lxml # May also use PIP % pip install pykml # Not available through conda Optional GDAL library --------------------- To create a pyramid of images for faster loading in Google Earth, you will also want to install the Geospatial Data Abstraction Library (`GDAL`_). This can be most easily installed with *conda*:: % conda install gdal On OSX, the GDAL library can also be installed through MacPorts or Homebrew. Depending on your installation, you may also need to set the environment variable 'GDAL_DATA' to point to the directory containing the projection files (e.g. gcs.cvs, epsg.wkt, and so on) needed to georeference and warp your PNG images. For example, in Anaconda Python, these support files are installed under the `share/gdal` directory, and so you can set (in bash) the environment variable as:: export GDAL_DATA=$ANACONDA/share/gdal An example : The Chile 2010 tsunami event ========================================= .. _Chile_2010.kml: http://math.boisestate.edu/~calhoun/visclaw/GoogleEarth/kml/Chile_2010.kml Simulations of the Chile 2010 earthquake and tsunami are included as an example in the GeoClaw module of Clawpack. Once you have run this simulation, you can create the KMZ file needed for visualizing your data in Google Earth by using the command:: % make plots "SETPLOT_FILE=setplot_kml.py" This runs the commands in *setplot_kml.py*. The resulting archive file *Chile_2010.kmz* (created in your plots directory) can be opened in Google Earth. An on-line version of results from this example can be viewed by opening the file `Chile_2010.kml`_ in Google Earth. .. figure:: images/GE_Chile.png :scale: 50% :align: center Simulation of the Chile 2010 tsunami (see geoclaw/examples/tsunami/chile2010). Plotting attributes needed for Google Earth ------------------------------------------- The plotting parameters needed to instruct VisClaw to create plots suitable for visualization in Google Earth are all set as attributes to instances of the VisClaw classes *ClawPlotData* and *ClawPlotFigure*. We describe each of the relevant attributes and refer to their usage in the Chile 2010 example file `setplot_kml.py` file. In what follows, we only refer to instances `plotdata` and `plotfigure` of the `ClawPlotData` and `ClawPlotFigure` classes, respectively. plotdata attributes ------------------- The following *plotdata* attributes apply to all VisClaw figures to be visualized in Google Earth. These attributes are all **optional** and have reasonable default values. .. code-block:: python def setplot(plotdata): # ..... #----------------------------------------- # plotdata attributes for KML #----------------------------------------- plotdata.kml_name = "Chile 2010" plotdata.kml_starttime = [2010,2,27,6,34,0] # Date and time of event in UTC [None] plotdata.kml_tz_offset = 3 # Time zone offset (in hours) of event. [None] plotdata.kml_index_fname = "Chile_2010" # name for .kmz and .kml files ["_GoogleEarth"] # Set to a URL where KMZ file will be published. # plotdata.kml_publish = None .. attribute:: kml_name : string Name used in the Google Earth sidebar to identify the simulation. Default : "GeoClaw" .. attribute:: kml_starttime : [Y,M,D,H,M,S] Start date and time, in UTC, of the event. The format is *[year,month,day,hour, minute, second]*. By default, local time will be used. .. attribute:: kml_timezone : integer Time zone offset, in hours, of the event from UTC. For example, the offset for Chile is +3 hours, whereas the offset for Japan is -9 hours. Default : no time zone offset. .. attribute:: kml_index_fname : string The name given to the KMZ file created in the plot directory. Default : "_GoogleEarth" .. attribute:: kml_publish : string A URL address and path to remote site hosting a KMZ file you wish to make available on-line. See `Publishing your results`_. plotfigure attributes --------------------- The following attributes apply to an individual figure created for visualization in Google Earth. The first three attributes are **required**. The rest are optional. .. code-block:: python #----------------------------------------------------------- # Figure - Sea Surface #---------------------------------------------------------- plotfigure = plotdata.new_plotfigure(name='Sea Surface',figno=1) plotfigure.show = True # Required KML attributes for visualization in Google Earth plotfigure.use_for_kml = True plotfigure.kml_xlimits = [-120,-60] # Longitude plotfigure.kml_ylimits = [-60, 0.0] # Latitude # Optional attributes plotfigure.kml_use_for_initial_view = True plotfigure.kml_figsize = [30.0,30.0] plotfigure.kml_dpi = 12 # Resolve all three levels plotfigure.kml_tile_images = False # Tile images for faster loading. Requires GDAL [False] .. attribute:: use_for_kml : boolean Indicates to VisClaw that the PNG file created for this figure should be suitable for visualization in Google Earth. With this set to `True`, all titles, axes labels, colorbars and tick marks will be suppressed. Default : `False`. .. attribute:: kml_xlimits : [longitude_min, longitude_max] Longitude range used to place PNG figure on Google Earth. *This setting will override any limits set as `plotaxes` attributes*. **Required** .. attribute:: kml_ylimits : [latitude_min, latitude_max] Latitude range used to place the PNG figure on Google Earth. *This setting will override any limits set as `plotaxes` attributes*. **Required** .. attribute:: kml_use_for_initial_view : boolean Set to `True` if this figure should be used to determine the initial camera position in Google Earth. The initial camera position will be centered over this figure, and at an elevation equal to approximately twice the width of the figure, in meters. By default, the first figure created will be used to set the initial view. .. attribute:: kml_figsize : [size_x_inches,size_y_inches] The figure size, in inches, for the PNG file. See `Removing aliasing artifacts`_ for tips on how to set the figure size and dpi for best results. Default : 8 x 6 (chosen by Matplotlib). .. attribute:: kml_dpi : integer Number of pixels per inch used in rendering PNG figures. This should be consistent with the `figsize` and the refinement factors. See `Removing aliasing artifacts`_ below for more details on how to improve the quality of the PNG files created by Matplotlib. Default : 200. .. attribute:: kml_tile_images : boolean Set to `True` if you want to create a pyramid of images at different resolutions for faster loading in Google Earth. *Image tiling requires the GDAL library*. See `Optional GDAL library`_, above, for installation instructions. Default : False. Creating the figures -------------------- All figures created for Google Earth are rendered as PNG files using the Matplotlib backend. So in this sense, the resulting PNG files are created in a manner that is no different from other VisClaw output formats. Furthermore, there are no special plotaxes or plotitems attributes to set for KML figures. But several attributes will either be ignored by the KML output or should be suppressed for best results in Google Earth. .. code-block:: python # Create the figure plotaxes = plotfigure.new_plotaxes('kml') # Create a pseudo-color plot. Render the sea level height transparent. plotitem = plotaxes.new_plotitem(plot_type='2d_pcolor') plotitem.plot_var = geoplot.surface_or_depth plotitem.cmin = -0.2 plotitem.cmap = 0.2 plotitem.pcolor_cmap = googleearth_transparent # Create a colorbar (appears as a Screen Overlay in Google Earth). def kml_colorbar(filename): cmin = -0.2 cmax = 0.2 cmap = geoplot.googleearth_transparent geoplot.kml_build_colorbar(filename,cmap,cmin,cmax) plotfigure.kml_colorbar = kml_colorbar plotaxes attributes ^^^^^^^^^^^^^^^^^^^ The plotaxes attributes `colorbar`, `xlimits`, `ylimits` and `title` will all be ignored by the KML plotting. For best results, the attribute `scaled` should be set to its default value `False`. The only plotaxes attribute that might be useful in some limited contexts is the `afteraxes` setting, and only if the `afteraxes` function does not add plot features that cause Matplotlib to alter the space occupied by the figure. In most cases, the `afteraxes` commands should not be needed or should not be used. plotitem attributes ^^^^^^^^^^^^^^^^^^^ The most useful `plotitem` type will probably be the `2d_pcolor` type, although other types including the filled contour `contourf` can also be used to good effect. The transparent colormap is particularly appealing visually when overlaid onto the Google Earth ocean bathymetry. This colormap is the `geoplot.googleearth_transparent` colormap, available in the geoplot module. Other colormaps that are designed to work well with the Google Earth browser backdrop are the `googleearth_lightblue` and `googleearth_darkblue` colormaps. These are solid colormaps, with the zero sea surface level set to colors which match those of the ocean bathymetry. Adding a colorbar overlay ^^^^^^^^^^^^^^^^^^^^^^^^^ A colorbar can be associated with each figure in the Google Earth browser by setting the figure attribute `colorbar`. The color axis range `[cmin, cmax]` and the colormap `cmap` should be consistent with those set as plotitem attributes. Gauges and miscellaneous settings --------------------------------- There are no particular attributes for gauge plots and so they can be created in the usual way. In the Google Earth browser, gauge locations will be displayed as Placemarks. Clicking on gauge Placemarks will bring up the individual gauge plots. The screenshot below shows the gauge plot that appears when either the gauge Placemark or the gauge label in the sidebar is clicked. .. figure:: images/GE_screenshot.png :scale: 20% :align: center Screenshot illustrating gauge plots. Additional plotdata attributes ------------------------------ VisClaw has additional plotdata attributes indicating which figures and frames to plot, and which output style to create. When plotting for Google Earth, one additional output parameter is necessary. .. code-block:: python #----------------------------------------- plotdata.print_format = 'png' # file format plotdata.print_framenos = 'all' # list of frames to print plotdata.print_fignos = 'all' # list of figures to print plotdata.html = False # create html files of plots? plotdata.latex = False # create latex file of plots? # .... plotdata.kml = True # Create a KML/KMZ file return plotdata # end of setplot_kml.py file .. attribute:: kml : boolean Set to `True` to indicate that a KML/KMZ file should be created. Default : False. Plotting tips ============= Below are tips for working with KML/KMZ files, creating zoomed images, improving the quality of your images and publishing your results. KML and KMZ files ----------------- KML files are very similar to HTML files in that they use `...` to describe data to be rendered by a suitable rendering engine. Like a web browser, Google Earth can be viewed as browser for geospatial data described by the KML-specific tags. The VisClaw `kml` attributes described above will create PNG files for frames, gauges and colorbars, and a hierarchy of linked KML files, including a top level `doc.kml` file for the entire simulation, one top level `doc.kml` file per figure, and additional referenced kml files per frame. These KML and image files will not appear individually in your plots directory, but are archived into a single KMZ file that you can load in Google Earth. If you would like to browse the individual images and KML files created by VisClaw, you can extract them from the KMZ file using an un-archiving utility. On OSX, for example, you can use `unzip` to extract one or more individual files from the KMZ file. Other useful `zip` utilities include `zip` (used to create the KMZ file initially) and `zipinfo`. One reason you might wish to view the contents of an individual KMZ file is to inspect the PNG images generated by Matplotlib and that will be used as GroundOverlays in the Google Earth browser. Another reason may be that you wish to make minor to edits the top level doc.kml file to add additional Google Earth sidebar entries or to change visibility defaults of individual folders. The KMZ file can be posted to a website to share your results with others. See `Publishing your results`_, below. Creating multiple figures at different resolutions -------------------------------------------------- You can create several figures for visualization in Google Earth. Each figure you create will show up in a separate folder in the Google Earth sidebar. For at least one figure, you will probably want to set the `kml_xlimits` and `kml_ylimits` to match the computational domain. To get higher resolution zoomed in figures, you will want to restrict the x- and y-limits to a smaller region. For best results, these zoom regions should be consistent with the resolution of your simulation. In the Chile example, a 30x30 inch figure resolves two degrees per inch. The x- and y-limits for the zoomed in figure should then span an even number of degrees in each direction, and have boundaries that align with even degree marks, i.e. -120, -118, -116, etc. In **setplot_kml.py**, the zoomed in region is described as : .. code-block:: python # Set Google Earth bounding box and figure size plotfigure.kml_xlimits = [-84,-74] # 10 degrees plotfigure.kml_ylimits = [-18,-4] # 14 degrees plotfigure.kml_figsize = [10,14] # inches. (1 inch per degree) # Resolution rcl = 10 # Over-resolve the coarsest level plotfigure.kml_dpi = rcl*2*6 # Resolve all three levels plotfigure.kml_tile_images = False # Tile images for faster loading. This figure shows up in the Google Earth sidebar as "Sea Surface (zoom)". See `Removing aliasing artifacts`_ for more details on how to set the zoom levels. .. _Creating an image pyramid: Tiling images for faster loading -------------------------------- If you create several frames with relatively high dpi, you may find that the resulting KMZ file is slow to load in Google Earth. In extreme cases, large PNG files will not load at all. You can improve Google Earth performance by creating an image hierarchy which loads only a low resolution sampling of the data at low zoom levels and higher resolution images suitable for close-up views. In VisClaw, this image pyramid is created by setting the plotfigure attribute `kml_tile_images` to `True`. .. code-block:: python plotfigure.kml_tile_images = True **Note:** This requires the GDAL library, which can be installed following the `Optional GDAL library`_ instructions, above. .. _Enhancing the resolution: Removing aliasing artifacts --------------------------- You may find that the transparent colormap leads to unappealing visual artifacts. This can happen when the resolution of the PNG file does not match the resolution of the data used to create the image. In the Chile example, the number of grid cells on the coarsest level is 30 in each direction. But the default settings for the figure size (`kml_figsize`) is `8x6` inches and dpi (`kml_dpi`) is 200, resulting in an image that is 1600 x 1200. But because 1600 is not an even multiple of 30, noticeable vertical stripes appear at the coarsest level. A more obvious plaid patterns appear at finer levels, since neither 1600 or 1200 are evenly divisible by 30*2*6 = 360. .. figure:: images/GE_aliased.png :scale: 50% :align: center Aliasing effects resulting from default `kml_dpi` and `kml_figsize` settings In the Chile example, we can remove these aliasing effects by making the resolution of the PNG file a multiple of 30*2*6 = 360. This can be done by setting the figure size and DPI appropriately:: # Set dpi and figure size to resolve the 30x30 coarse grid, and two levels of refinement with # refinement factors of 2 and 6. plotfigure.kml_figsize = [30,30] plotfigure.kml_dpi = 12 The resulting PNG file has a resolution of only 360x360, but in fact, is free of the vertical and horizontal stripes that appeared in the default, much higher resolution image. .. figure:: images/GE_nonaliased.png :scale: 200% :align: center Aliasing effects removed by properly setting `kml_dpi` and `kml_figsize` While the above removes aliasing artifacts, you may still find that the resolution is unacceptable, especially in close-up views of shorelines and so on. In this case, you can increase the resolution of the figure in integer factors that remain consistent with the coarse grid and refinement factors. It might not be possible to fully resolve all levels of a large simulation with many refinement levels because the resulting image resolution exceeds the Matplotlib limit of 32768 pixels on a side. In this case, you can limit the number of levels that are resolved by a particular figure and create zoomed in figures that resolve finer levels. Alternatively, you can break the computational domain into several figures, each covering a portion of the entire domain. The Chile example shows a zoomed in figure near the shoreline with increased resolution at all levels. .. _Publishing your results: Publishing your results ----------------------- You can easily share your results with collaborators by providing links to your archive KMZ file in HTML webpages. Collaborators can download the KMZ file and open it in a Google Earth browser. However, you may find that the KMZ file is too large to make downloading convenient. In this case, you can provide a light-weight KML file that contains a link to your KMZ file stored on a host server. Collaborators can then open this KML file in Google Earth and browse your results via an internet connection. To create this KML file, you should set the `plotdata` attribute `kml_publish` to the url address of your host server where the KMZ files will be stored. For example, the Chile file above is stored at:: plotdata.kml_publish = "http://math.boisestate.edu/~calhoun/visclaw/GoogleEarth/kmz" VisClaw will detect that this `plotdata` attribute has been set and automatically create a KML file that refers to the linked file "Chile_2010.kmz", stored at the above address. This KML file (see `Chile_2010.kml`_ for an example) can be easily shared or posted on webpages to allow collaborators to view your results via links to your remotely stored KMZ file. The KML file is set to automatically load an updated KMZ file every 5 minutes. You can easily change this setting by editing the KML file. By default, `plotdata.kml_publish` is set to `None`, in which case, no KML file will be created.