reskit.util.topography
======================

.. py:module:: reskit.util.topography


Attributes
----------

.. autoapisummary::

   reskit.util.topography.ext


Functions
---------

.. autoapisummary::

   reskit.util.topography.visibility_from_topography


Module Contents
---------------

.. py:function:: visibility_from_topography(lon, lat, elevation_raster, base_elevation=None, eye_level=2, max_degree=0.1, degree_step=0.003, theta_step=3, _interpolation='cubic')

   Determine visibility around a given point based on topography. Also
   gives planar angle, planar elevation, and planar distance of multiple
   sample points surroudning the specified latitude and longitude


   Params:
   ======
   lon : longitude point to consider
   lat : latitude point to consider
   elevation_raster : The raster to extract elevation values from
   eye_level : The height to measure visibility from (in meters) above the elevation at the center point
   base_elevation : The total height to measure visibility from (in meters)
       - If given, 'eye_level' is ignored
   max_degree : The maximum distance to consider (in degrees)
   degree_step : approximate radial degree discretization
   theta_step : theta discretization

   Return:
   ======
   dict
       - All items are pandas DataFrames
           * Columns match to theta direction (in radians)
       - Items include:
           * latitude : the latitude at each sample point
           * longitude : the longitude at each sample point
           * planar_angle : the angle between the view point and the sample point
           * planar_dist : the planar distance between the view point and the sample point
           * planar_elev : the planar elevation of the sample point
           * visibility : indicates if the sample point should be visible from the view point

   Note:
   =====
   * This algorithm will likely fail if used too near to the poles
   * It is also important to choose an appropriate degree_step for the
     given elevation raster file. If the step size is too small,
     artifacts will begin to appear in leading to reduced visibility
     - Todo: investigate this further?? (It has something to do with
       the interpolation
     - For now, choose a value which is slightly higher than the raster's
       pixel resolution

   * You can plot the outputs nicely with:
      >>> fig = plt.figure()
      >>> ax = (
      ...     fig.add_subplot(
      ...         111,
      ...         polar=True,
      ...     )
      ... )
      >>> h = ax.pcolormesh(a['visibility'].columns,
      >>>                   a['visibility'].index,
      >>>                   a['visibility'])
      >>> plt.colorbar(h)
      >>> plt.show()


.. py:data:: ext