wolfhece.rem.RasterViz
======================
.. py:module:: wolfhece.rem.RasterViz
Module Contents
---------------
.. py:data:: start
.. py:data:: usage
:value: Multiline-String
.. raw:: html
<details><summary>Show Value</summary>
.. code-block:: python
"""
Python script for OpenTopography Raster Derivative/Visualization products.
This script can be called from Python using its class/methods or as a CLI utility.
CLI Usage:
"python RasterViz.py viz_type [-z (default=1)] [-alt (default=45)] [-azim (default=315)] [-multidirectional]
[-cmap (default=terrain)] [-out_ext tif | img (default=tif)] [-make_png] [-make_kmz] [-docker] [-shell]
/path/to/dem"
Options:
viz_type: string corresponding to raster product to be produced, one of the following strings:
["hillshade", "slope", "aspect", "roughness", "color-relief", "hillshade-color"]
-z: only if using "hillshade" or "hillshade-color" viz_type,
factor to scale/exaggerate vertical topographic differences. Default 1 (no rescale).
-alt: only if using "hillshade" or "hillshade-color" viz_type,
altitude of light source in degrees [0-90]. Default 45.
-azim: only if using "hillshade" or "hillshade-color" viz_type,
azimuth of light source in degrees [0-360]. Default 315.
-multidirectional: only if using "hillshade" or "hillshade-color" viz_type.
Makes multidirectional hillshade, overriding alt and azim args.
-cmap: only if using "color-relief" viz_type, name of a matplotlib or seaborn colormap. Default "terrain".
(see https://matplotlib.org/stable/gallery/color/colormap_reference.html)
-out_ext: the extension/file format to use for geodata outputs (tif or img). Default "tif".
-make_png: output a png version (EPSG:3857) of the viz_type in addition to the viz raster in source projection.
-make_kmz: output a kmz version of the viz_type in addition to the viz raster in source projection.
-docker: run GDAL commands from within the osgeo/gdal docker container. This makes it run slightly slower but will
be needed to run all features if gdal install is on a version <2.2. If using docker, input path must be
within the working directory path or a subdirectory.
-shell: call GDAL functions (gdaldem, gdal_translate, gdalwarp) as shell commands instead of using Python bindings.
This may be faster than using pure Python but requires additional environment configuration.
/path/to/dem.tif: path to input DEM, currently assumed to be in GeoTIFF format.
Notes: Output file naming convention uses the DEM basename as a prefix, then viz_type and file extension.
E.g. output.tin.tif --> output_hillshade.tif, output_hillshade.png, output_hillshade.kmz.
Outputs are saved to the working directory.
Dependencies:
- Python >=3.6
- GDAL >=2.2 (or run with lower version in environment using -docker flag)
"""
.. raw:: html
</details>
.. py:function:: print_usage()
.. py:class:: RasterViz(dem, out_dir='./', out_ext='.tif', make_png=False, make_kmz=False, docker_run=False, shell=False, cache_dir='./.cache', *args, **kwargs)
Bases: :py:obj:`object`
Handler to produce DEM derivatives/visualizations.
:param dem: path to input DEM, either in GeoTIFF (.tif), ASCII (.asc), or IMG (.img) format.
:type dem: str
:param out_dir: output file directory. Defaults to current working directory.
:type out_dir: str
:param out_ext: extension for output georaster files.
:type out_ext: str, '.tif' or '.img'
:param make_png: output a png image of visualizations (EPSG:3857) in addition to a raster in source projection.
:type make_png: bool
:param make_kmz: output a kmz file (e.g. Google Earth) of visualizations in addition to a raster in source
projection.
:type make_kmz: bool
:param docker_run: only if shell=True as well, calls gdal utilities from shell with docker container. Must have the
osgeo/gdal docker container configured locally to use this option.
:type docker_run: bool
:param shell: call gdal utilities from a shell instead of using the Python bindings. May run faster for large files
but can be more difficult to configure GDAL environment outside conda.
:type shell: bool
:param cache_dir: cache directory
:type cache_dir: str
.. py:property:: out_dir
.. py:property:: cache_dir
.. py:attribute:: shell
:value: False
.. py:attribute:: ext
:value: '.tif'
.. py:attribute:: format_dict
.. py:attribute:: out_format
:value: 'GTiff'
.. py:property:: dem
.. py:attribute:: dem_name
.. py:attribute:: scale
:value: 111120
.. py:attribute:: viz_srs
:value: 'EPSG:3857'
.. py:attribute:: make_png
:value: False
.. py:attribute:: make_kmz
:value: False
.. py:attribute:: viz_types
.. py:attribute:: intermediate_rasters
.. py:attribute:: out_rasters
.. py:attribute:: hillshade_ras
.. py:attribute:: color_relief_ras
.. py:method:: valid_input(dem)
:staticmethod:
.. py:method:: _asc_to_tif(asc)
Convert ascii grid to geotiff
.. py:method:: _check_dem_nodata()
Check that input DEM has a NoData value set. If not, set to zero.
.. py:method:: _png_kmz_checker()
Used as a wrapper for making viz products, making png and kmz after tif if selected
.. py:method:: make_hillshade(z=1, alt=45, azim=315, multidirectional=False, *args, **kwargs)
Make hillshade raster from the input DEM.
:param z: z factor for exaggerating vertical scale differences (default 1).
:type z: float >1
:param alt: altitude of light source in degrees (default 45).
:type alt: float [0-90]
:param azim: azimuth for light source in degrees (default 315).
:type azim: float [0-360]
:param multidirectional: makes multidirectional hillshade if True, overriding alt and azim.
:type multidirectional: bool
:returns: path to output hillshade raster.
:rtype: str
.. py:method:: make_slope(*args, **kwargs)
Make slope map from DEM, with slope at each pixel in degrees [0-90].
:returns: path to output slope raster.
:rtype: str
.. py:method:: make_aspect(*args, **kwargs)
Make aspect map from DEM, with aspect at each pixel in degrees [0-360].
:returns: path to output aspect raster.
:rtype: str
.. py:method:: make_roughness(*args, **kwargs)
Make roughness map from DEM.
:returns: path to output roughness raster.
:rtype: str
.. py:method:: make_color_relief(cmap='terrain', log_scale=False, *args, **kwargs)
Make color relief map from DEM (3 band RGB raster).
:param cmap: matplotlib or seaborn named colormap to use for making color relief map.
(see https://matplotlib.org/stable/gallery/color/colormap_reference.html)
:type cmap: str
:param log_scale: bool, makes the colormap on a log scale from zero, so terrain closer to 0 elevation
has greater color variation. Intended to be used for REMs or coastal datasets.
:type log_scale: bool
:returns: path to output color-relief raster.
:rtype: str
.. py:method:: make_hillshade_color(blend_percent=60, *args, **kwargs)
Make a pretty composite hillshade/color-relief image.
:param blend_percent: Percent weight of hillshdae in blend, color-relief takes opposite weight.
:type blend_percent: float [0-100]
This method also accepts all arguments of `make_hillshade` and `make_color_relief` if the respective rasters
have not yet been created.
:returns: path to output hillshade-color raster.
:rtype: str
.. py:method:: blend_images(blend_percent=60)
Blend hillshade and color-relief rasters by linearly interpolating RGB values
:param blend_percent: Percent weight of hillshdae in blend, color-relief takes opposite weight [0-100]. Default 60.
.. py:method:: get_cmap_txt(cmap='terrain', log_scale=False)
Make a matplotlib named colormap into a gdaldem colormap text file for color-relief mapping.
Format is "elevation R G B" where RGB are in [0-255] range.
:param cmap: colormap to use for making color relief map.
:param log_scale: bool, logarithmically scale colormap, showing greatest color variation at zero elevation.
Intended to be used for REMs or coastal datasets.
:return: .txt file containing colormap mapped to DEM
.. py:method:: get_projection()
Get EPSG code for DEM raster projection.
.. py:method:: get_elev_range()
Get range (min, max) of DEM elevation values.
.. py:method:: tile_and_compress(in_path, out_path)
Used to turn intermediate raster viz products into final outputs.
.. py:method:: raster_to_png(ras_path)
Convert raster to .png file. Coerce to EPSG:3857 consistent with existing OT service.
.. py:method:: raster_to_kmz(ras_path)
Convert .tif raster to .kmz file
.. py:method:: get_scaling(ras_name)
:staticmethod:
Get scaling string for gdal_translate call when converting to Byte array for png/kmz outputs
.. py:method:: _clean_up()
Delete all intermediate files. Called by _png_kmz_checker decorator at end of function calls.
.. py:data:: argv