height_map_data#

pycraf.pathprof.height_map_data(lon_t, lat_t, map_size_lon, map_size_lat, map_resolution=<Quantity 3. arcsec>, do_cos_delta=True, zone_t=<CLUTTER.UNKNOWN: -1>, zone_r=<CLUTTER.UNKNOWN: -1>, d_tm=None, d_lm=None, d_ct=None, d_cr=None, omega_percent=<Quantity 0. %>, do_lonlat_profs=False, cache_path=None, clobber=False)[source]#

Calculate height profiles and auxillary maps needed for atten_map_fast.

This can be used to cache height-profile data. Since it is independent of frequency, timepercent, Tx and Rx heights, etc., one can re-use it to save computing time when doing batch jobs.

The basic idea is to only calculate the height profiles between each of the pixels on the map edges (super-sampled with a factor of ~3) and the map center. The me height profiles have different lengths, because the distance to the pixels on the edges varies (e.g., corners have the largest distance from the center). For shorter profiles, the arrays are zero-padded such that all me profiles have the same length mh. They are stored in a 2D array, called height_profs. Associated with this, a 1D array, dist_prof, contains the associated path distances. It has length mh. For convenience, also a zero-valued array, zheight_prof is stored, having length mh. This is used for the flat-Earth calculations in P.452.

Now, for each other pixel in the map, we have to find out, which of the above height profile paths comes closest (with one of its elements) to the pixel in question. The identified path ID is stored in path_idx_map, and the index of the distance element in that path is kept in dist_end_idx_map. For debugging reasons, the angular distance of the “best” path is provided in pix_dist_map, but this is not used in atten_map_fast.

Parameters:
lon_t, lat_tQuantity

Geographic longitude/latitude of transmitter [deg]

map_size_lon, map_size_latQuantity

Map size in longitude/latitude[deg]

map_resolutionQuantity, optional

Pixel resolution of map [deg] (default: 3 arcsec)

do_cos_deltabool, optional

If True, divide map_size_lon by cos(lat_t) to produce a more square-like map. (default: True)

zone_t, zone_rCLUTTER enum, optional

Clutter type for transmitter/receiver terminal. (default: CLUTTER.UNKNOWN)

d_tmQuantity, optional

longest continuous land (inland + coastal) section of the great-circle path [km] (default: distance between Tx and Rx)

d_lmQuantity, optional

longest continuous inland section of the great-circle path [km] (default: distance between Tx and Rx)

d_ct, d_crQuantity, optional

Distance over land from transmitter/receiver antenna to the coast along great circle interference path [km] (default: 50000 km)

omega_percentQuantity, optional

Fraction of the path over water [%] (see Table 3) (default: 0%)

do_lonlat_profsbool, optional

If True, also add lons_profs and lats_profs to output dict. (See below for further information. Default: False)

cache_pathstr, optional

If set, the joblib package is used to cache results provided by this function on disk, such that future queries are executed much faster. If set to None, no caching is performed. (default: None)

clobberbool, optional

If set to True and caching is active re-compute the result even if an older result is found in cache. This is useful, when something has change with the underlying terrain data, e.g., new tiles were downloaded. (default: False)

Returns:
hprof_datadict

Dictionary with height profiles and auxillary data as calculated with height_map_data.

The dictionary contains the following entities (the map dimension is mx * my):

  • “lon_t”, “lat_t” : float

    Map center coordinates.

  • “map_size_lon”, “map_size_lat” : float

    Map size.

  • “hprof_step” : float

    Distance resolution of height profile.

  • “do_cos_delta” : int

    Whether cos-delta correction was applied for map size creation.

  • “xcoords”, “ycoords” : ndarray 1D (float; (mx, ); (my, ))

    Longitude and latitude coordinates of first row and first column in the map

  • “lon_mid_map”, “lat_mid_map” : ndarray 2D (float; (mx, my))

    Longitude and latitude path center coordinates for each pixel w.r.t. map center.

    This is returned for information, only. It is not needed by atten_map_fast!

  • “dist_map” : ndarray 2D (float; (mx, my))

    Distances to map center for each pixel.

  • “d_ct_map”, “d_cr_map” : ndarray 2D (float; (mx, my))

    The d_ct and d_cr values for each pixel in the map.

  • “d_lm_map”, “d_tm_map” : ndarray 2D (float; (mx, my))

    The d_lm and d_tm values for each pixel in the map.

  • “omega_map” : ndarray 2D (float; (mx, my))

    The omega values for each pixel in the map.

  • “zone_t_map”, “zone_r_map” : ndarray 2D (CLUTTER enum; (mx, my))

    The clutter zone types zone_t and zone_r for each pixel in the map.

  • “bearing_map”, “back_bearing_map” : ndarray 2D (float; (mx, my))

    The bearing and backbearing values for each pixel in the map.

    This is returned for information, only. It is not needed by atten_map_fast!

  • “N0_map”, “delta_N_map”, “beta0_map” : ndarray 2D (float; (mx, my))

    The N0, delta_N, and beta0 values for each pixel in the map.

  • “path_idx_map” : ndarray 2D (int; (mx, my))

    Path IDs for each pixel in the map. With this index, one can query the associated height profile from height_profs.

  • “pix_dist_map” : ndarray 2D (float; (mx, my))

    Angular distance of the closest path to each of the map pixels.

  • “dist_end_idx_map” : ndarray 2D (int; (mx, my))

    Index of the last element in the dist/height profiles to be used when querying the profiles from dist_prof and height_profs.

  • “dist_prof” : ndarray 1D (float, (mh, ))

    Distance values for each of the paths stored in height_profs.

  • “height_profs” : ndarray 2D (float, (me, mh))

    Height profiles to each of the pixels on the map edge, zero padded.

  • “zheight_prof” : ndarray 1D (float, (mh, ))

    Zero-valued array of the same length as height_profs for convenience.

  • “lons_profs” : ndarray 2D (float, (me, mh))

    Longitude (profiles) to each of the pixels on the map edge, zero padded. This can be useful, if one wants to tinker with the height_profs based on the coordinates of its values. (An example would be to add clutter heights.)

  • “lons_profs” : ndarray 2D (float, (me, mh)) As lats_profs but for latitudes.

Notes

  • Path attenuation is completely symmetric, i.e., it doesn’t matter if the transmitter or the receiver is situated in the map center.

  • SRTM data tiles (*.hgt) need to be accessible by pycraf. It is assumed that these are either present in the current working directory or in the path defined by the SRTMDATA environment variable (sub-directories are also parsed). Alternatively, use the SrtmConf manager to change the directory, where pycraf looks for SRTM data, during run-time. The SrtmConf manager also offers additional features such as automatic downloading of missing tiles or applying different interpolation methods (e.g., splines). For details see Working with SRTM data.