touchterrain 2.5: New Hillshading, more DEM sources, lower_leq setting and new folder structure (May 13)

The May 13 release of touchterrain (v. 2.5) contains a whole bunch of new and changed features:

New Hillshading

• Hillshading creates a overlay map that shows a pseudo-3D relief of the underlying DEM. This is useful as a pre-visualization of how your 3D print will roughly look and helps users to select interesting areas to print.
• Hillshading (in its simplest form) assumes that a sun is positioned above the terrain at certain angles:
• Azimuth: Defines the direction (compass heading) from which the Sun shines to create the hillshade relief. Note that South will typically result in a flipped relief perception!
• Elevation: Defines the vertical Sun angle, i.e. how high the Sun is above the horizon. Use it to enhance detail for different types of terrain.
• So basically we have a 2 angles, a horizontal (0 - 360, 0 = North) and vertical (0 - 90, 90 = perfectly above) that define the position of the light source used to create the impression of a 3D relief by creating greyscale values from 0 (dark) to 255 (super bright). Note that this does not create shadows, only the effect of specular highlights, which is a very strong perceptional cues for creating a 3D effect.
• The standard hillshade parameter values are: azimuth of 315° (NNE) and 45° for elevation, which are good all-around settings.
• However, it can be fun (and rewarding) to change these angles, which is what the new version allows you to do (in a limited fashion)!
• For example, for best results the Sun should come at an angle roughly perpendicular to ridges in your terrain. Here's a comparison for different azimuth values (elevation angle is 60) (source):
  
  
  
  

• 270, 315, 0 and 45 all bring out different aspects of the same data, e.g. 45 emphasizes NE-SW oriented features. Also, to me, some values seem to make my brain reverse the topography i.e. ridges look like valleys and vice versa. 
• Looking at the elevation value, values lower than 45, create darker and darker overlays but also more and more emphasize low relief terrain features, such as drainage channels (but at the cost of blowing out high relief features).
• For touchterrain 2.5 I have attempted to implement a simple way to experiment with these two hillshade angles without overwhelming and confusing the user:
• Sun direction (new) has a few direction presets shown as words (West, North-West, etc.). I only sweep the northern directions in 45 steps b/c I'm pretty sure that using southern direction would result in relief confusion. But, just to force the effect I include South as well.
• I renamed the Elevation parameter to Sun Angle (b/c I want to avoid confusion with terrain elevation) and again offer just a few presets: Normal (45), Steep (55) and several progressively flatter settings to go below 45 all the way to 5
• Finally there's a gamma value via a direct number input. This gamma correction factor is used to somewhat compensate that low sun angles tend to create hillshades that look too dark.  Gamma values > 1 increase the "lightness" so as the sun angle becomes lower, this gamma will increase to compensate. Note that the specific gamma values are my "opinion" only! If you want to tweak the gamma after selecting a sun angle preset, just change the number and hit enter. Feel free to experiment, but be aware that your tweak will be overwritten next time you choose another sun angle preset!
  
• Be aware that changing any of the hillshade parameters will require a reload of the map, b/c I need to give Earth Engine these new values, get back a new hillshade overlay calculated for the new values and then display it. So it might take a split second, depending on your internet.
• Note that I have tried to preserve all other input values you might have chosen before doing such a reload. This includes the type of Google Map map in the background and the transparency. However, this is not fully tested, so please let me know if values for some fields you changed earlier are getting reset.
• If you're curious, go and change the Google Map to Terrain (Map -> Terrain), which also has hillshading backed in, and lower your transparency to mix them both.
• Transparency (inverse of opacity) is still given in percent but I made the slider much, much smoother (1% steps). I also removed the direct numeric input b/c I feel having a precise number value is not how transparency is used, user should simple move the slider until they are happy.  Changing Transparency will not trigger a reload, b/c it's set via your browser (client) not via the server.
• Finally, there are a bunch of new query parameters in the URL that store the new hillshade settings and transparency: transp= 0 -100,  hsazi= -360 - 360 (hs azimuth), hselev=  0 - 90 (hs elevation) and gamma= 0 - 99, so if you need values that cannot be generated in the GUI, just change those in the URL and hit enter. Note that none of these parameters matter when processing the terrain into 3D models, they are purely for a better visual experience.
  
• So ... got nuts and play with these values!  Set the transparency to 0 (full left) and set the Sun angle to extremely flat. I think this looks very interesting (or at least artistic :)

More DEM sources

• I have added a few new sources and added a link to their meta data (via earth engine):
• USGS/NED: 10 m, continental USA only. link
• ALOS DSM: Global: 30 m, worldwide, but has some small "holes". link
• USGS/SRTMGL1_003: 30 m, "worldwide", but not very far north (lower quality and older than ALOS!). link
• USGS/GMTED2010: ~230 m, truly worldwide. link
• GTOPO30: 30 Arc-Second, 1000 m, 1996, worldwide. link
• CryoSat-2 Antarctica: 1000 m, antarctica only. link
• NOAA/NGDC/ETOPO1: 2000 m, worldwide, with bathymetry. link
• For any non-US area ALOS should be your preferred choice as it's much newer and of better quality. However, it misses data in a few tiny areas ("holes")
• Using the Antarctica data is sadly a bit silly at the moment b/c Google maps are way too distorted.

lower_leq setting

• 
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  Thanks to Iden Craven a manual setting was added to lower any elevation values that are lower than a threshold (say <= 0 m, i.e. anything not land) by a millimeter value when printed out.
• Example "lower_leq":[0, 5] as a manual setting will lower offshore areas by 5 mm.
• This can emphasize shorelines while still printing area below sealevel. (ignore_leq would completely omit these areas when printed)

 New folder structure

• I decided to create a proper module for most of the touchterrain code, which required a new folder structure:
• standalone was remove and the two "main" files TouchTerrain_standalone.py, and its jupyter notebook version, TouchTerrain_standalone_jupyter_notebook.ipynb (recommended) are now at the root level.
• All other code (the common and server folders) was moved into a new folder called touchterrain
• Before running the stand alone version, a module called touchterrain needs to be build and installed in your system's site-packages folder. This is done via setup.py, best by using pip: pip install . <-dot!
• The jupyter notebook now explains the installation and can even run it inside a cell as a shell command!
• auxiliary files (examples, etc.) were mover to a new folder called stuff