infresnel — API Reference

infresnel.infresnel.calculate_paths(src_lat, src_lon, rec_lat, rec_lon, dem_file=None, full_output=False, return_dem=False, n_jobs=1)[source]

Calculate elevation profiles, direct paths, and shortest diffracted paths.

Paths are calculated for a given DEM (either a user-supplied dem_file or automatically downloaded 1 arc-second SRTM data) and an arbitrary number of source-receiver pairs. By default, the function returns only the direct and shortest diffracted path lengths. If full_output is set to True, then complete path information (lengths, coordinates, etc.) is returned.

Note

Input coordinates are expected to be in the WGS 84 datum. DEM file vertical units are expected to be meters.

Parameters:

  • src_lat (int or float) – Source latitude

  • src_lon (int or float) – Source longitude

  • rec_lat (int, float, list, tuple, or ndarray) – One or more receiver latitudes

  • rec_lon (int, float, list, tuple, or ndarray) – One or more receiver longitudes

  • dem_file (str or None) – Path to DEM file (if None, then SRTM data are used)

  • full_output (bool) – Toggle outputting full profile/path information vs. just direct and shortest diffracted path lengths

  • return_dem (bool) – Toggle additionally returning the UTM-projected DEM used to compute the profiles

  • n_jobs (int) – Number of parallel jobs to run (default is 1, which means no parallelization) — this argument is passed on to joblib.Parallel

Returns:

If full_output is False — an ndarray with shape (2, n_receivers) containing the direct path lengths [m] (first row) and shortest diffracted path lengths [m] (second row) for each source-receiver pair.

If full_output is True — a list of Dataset objects, one per source-receiver pair, containing full profile and path information

For either of the above cases, if return_dem is True, then the function returns a tuple of the form (output_array, dem) where output_array is the output described above, and dem is a DataArray containing the UTM-projected DEM used to compute the profiles

infresnel.infresnel.calculate_paths_grid(src_lat, src_lon, x_radius, y_radius, spacing, dem_file=None, output_file=None, n_jobs=1)[source]

Calculate paths for a UTM-projected grid surrounding a source location.

Wrapper around calculate_paths() for computing path difference grids. See the docstring for that function for a description of how DEM data are handled.

Note

Input coordinates are expected to be in the WGS 84 datum. DEM file vertical units are expected to be meters.

Parameters:

  • src_lat (int or float) – Source latitude

  • src_lon (int or float) – Source longitude

  • x_radius (int, float, list, or tuple) – [m] Desired grid radius in \(x\)-direction, measured from source location (specify a two-element array for different west and east extents)

  • y_radius (int, float, list, or tuple) – [m] Desired grid radius in \(y\)-direction, measured from source location (specify a two-element array for different south and north extents)

  • spacing (int or float) – [m] Desired grid spacing

  • dem_file (str or None) – Path to DEM file (if None, then SRTM data are used)

  • output_file (str or None) – If a string filepath is provided, then an RGB GeoTIFF file containing the colormapped grid of path length difference values is exported to this filepath (no export if None)

  • n_jobs (int) – Number of parallel jobs to run (default is 1, which means no parallelization) — this argument is passed on to joblib.Parallel

Returns:

Tuple of the form (path_length_differences, dem) where path_length_differences is a DataArray grid of path length differences [m], and dem is a DataArray containing the UTM-projected DEM used to compute the profiles

Return type:

tuple