topography — Topography helpers¶
The topography module provides a simple interface to world wide
elevation models. It implements simple getter functions,
elevation() and
geoid_undulation(), in order to access the default
topography model. For test purpose alternative models can also be instanciated
as Topography object.
The topography elevation data are stored in a local cache within the grand
user space. The update_data() allows to manage this
cache.
Warning
Topography elevation data are not automatically downloaded. They must be
requested explicitly with the update_data() function
before calling elevation().
Default interface¶
Warning
The input coordinates to the elevation() and
geoid_undulations() functions must be a grand
frame, i.e. ECEF or LTP. If magnetic
coordinates are used, the observation time must be specified as well.
Note
The elevation() and
geoid_undulations() functions accept vectorized data.
The returned value is a Quantity in meters.
-
grand.topography.distance(position: Union[ECEF, LTP], direction: Union[ECEF, LTP], maximum_distance: Optional[Quantity] = None) → Quantity¶ Get the signed intersection distance with the topography.
Note
The returned distance is signed. A positive (negative) value indicates that the initial position is above (below) the ground. The absolute value gives the actual distance.
-
grand.topography.elevation(coordinates: Union[ECEF, LTP], reference: Optional[grand.tools.topography.Reference] = None) → Quantity¶ Get the topography elevation, w.r.t. sea level or w.r.t. the ellipsoid.
For example, the following provides the topography elevation, w.r.t. the sea level, close to Urumuqi, China, provided that the corresponding data have been cached.
>>> coordinates = ECEF(latitude=43.83 * u.deg, longitude=87.62 * u.deg, ... representation_type='geodetic') >>> elevation = topography.elevation(coordinates, ... reference=topography.Reference.GEOID)
Note
By default, if no explicit reference is specified, the elevation is given w.r.t. the ellipsoid if geocentric coordinates are used (ECEF) or in local coordinates if local coordinates (LTP) are provided. In the latter case, the elevation data naturally include the Earth curvature.
-
grand.topography.geoid_undulation(coordinates: Union[ECEF, LTP]) → Quantity¶ Get the geoid undulation.
For example, the following corrects the previous elevation from the geoid undulation.
>>> elevation += topography.geoid_undulation(coordinates)
Cache management¶
Topography elevation data are cached in the user space, under
cachedir(). The cache can be managed with the
update_data() function.
-
grand.topography.update_data(coordinates: Union[ECEF, LTP, None] = None, clear: bool = False, radius: Optional[Quantity] = None)¶ Update the cache of topography data.
If coordinates are provided, the corresponding data tiles are downloaded to the cache. The requested area can be enlarged by specifying a radius around the coordinates. For example, the following ensures that the elevation data within 10 km of coordinates are available in the cache:
>>> topography.update_data(coordinates, radius=10 * u.km)
If clear is set to True (defaults to false) the cache is emptied. This occurs before any other operation, i.e. it can be combined with a data request.
-
grand.topography.cachedir() → Path¶ Get the location of the topography data cache.
Alternative topography models¶
Warning
In order to get the topography elevation from the default GRAND model
(SRTMGL1), one should not directly instantiate a
Topography object. Instead one should use the
elevation() function of the topography
module. This class is only meant to be used for studies of the impact of
alternative models.
Note
Currently only SRTMGL1 tiles are in the store. Data for
alternative models must be provided manually.
-
class
grand.topography.Topography(path: Union[pathlib.Path, str])¶ Proxy to topography data.
For example, assuming that you have the topography tiles corresponding to ASTER GDEM2 in your cache, the following allows to access those.
>>> topo = topography.Topography('ASTER-GDEM2')