windwhisper.elevation_grid
==========================

.. py:module:: windwhisper.elevation_grid

.. autoapi-nested-parse::

   Utilities for retrieving and interpolating elevation grids.



Attributes
----------

.. autoapisummary::

   windwhisper.elevation_grid.GOOGLE_API_KEY
   windwhisper.elevation_grid.ELEVATION_API
   windwhisper.elevation_grid.MAX_SAMPLING_POINTS


Functions
---------

.. autoapisummary::

   windwhisper.elevation_grid.get_elevation_grid
   windwhisper.elevation_grid.clip_array_around_turbines
   windwhisper.elevation_grid.distances_with_elevation


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

.. py:data:: GOOGLE_API_KEY

.. py:data:: ELEVATION_API

.. py:data:: MAX_SAMPLING_POINTS

.. py:function:: get_elevation_grid(longitudes, latitudes, elevation_data=None, wind_turbines = None)

   Return a terrain elevation grid for the target domain.

   :param longitudes: Longitudes defining the interpolation grid.
   :type longitudes: numpy.ndarray
   :param latitudes: Latitudes defining the interpolation grid.
   :type latitudes: numpy.ndarray
   :param elevation_data: Optional local dataset used instead of remote APIs.
   :type elevation_data: xarray.DataArray | None
   :param wind_turbines: Turbine specifications including ``position`` tuples.
   :type wind_turbines: dict | None
   :returns: Elevation grid interpolated to the provided coordinates or
       ``None`` when the remote request fails.
   :rtype: xarray.DataArray | None


.. py:function:: clip_array_around_turbines(da, wind_turbines, buffer_km=5.0)

   Clip an elevation grid around the wind turbines.

   :param da: Elevation array with ``latitude`` and ``longitude`` coordinates.
   :type da: xarray.DataArray | xarray.Dataset
   :param wind_turbines: Turbine specifications including ``position`` tuples
       expressed as ``(lat, lon)``.
   :type wind_turbines: dict
   :param buffer_km: Distance around each turbine to retain, in kilometres.
   :type buffer_km: float
   :returns: Elevation subset covering all turbines and their buffers.
   :rtype: xarray.DataArray
   :raises ValueError: If the dataset does not contain an ``'elevation'``
       variable when a dataset is provided instead of a data array.


.. py:function:: distances_with_elevation(distances, relative_elevations)

   Compute 3D distances using surface distance and elevation deltas.

   :param distances: Surface distances between points (typically from
       haversine calculations).
   :type distances: xarray.DataArray
   :param relative_elevations: Elevation differences between the same point
       pairs.
   :type relative_elevations: xarray.DataArray
   :returns: Distances adjusted for the elevation component.
   :rtype: xarray.DataArray
   :raises AssertionError: If the provided arrays do not share the same shape.