itur.utils package¶

itur.utils is a utilities library for ITU-Rpy.

This utility library for ITU-Rpy contains methods to: * Load data and build an interpolator object. * Prepare the input and output arrays, and handle unit transformations. * Compute distances and elevation angles between two points on Earth and or space.

itur.utils.load_data_interpolator(path_lat, path_lon, path_data, interp_fcn, flip_ud=True)[source]¶

Load a lat-lon tabulated dataset and build an interpolator.

Parameters:	path_lat (string) – Path for the file containing the latitude values path_lon (string) – Path for the file containing the longitude values path_data (string) – Path for the file containing the data values interp_fcn (string) – The interpolation function to be used flip_ud (boolean) – Whether to flip the latitude and data arrays along the first axis. This is an artifact of the format that the ITU uses to encode its data, which is inconsistent across recommendations (in some recommendations, latitude are sorted in ascending order, in others they are sorted in descending order).
Returns:	interp – An interpolator that given a latitude-longitude pair, returns the data value
Return type:	interp_fcn

itur.utils.load_data(path, is_text=False, **kwargs)[source]¶

Load data files from ./itur/data/.

Loads data from a comma-separated values file. The contents of the file can be numeric or text-based.

Parameters:	path (string) – Path of the data to load is_text (bool) – Indicates whether the data is text (True) or numerical (False). Default value is False.
Returns:	data – Numpy-array with the data. Numerical data is returned as a float
Return type:	numpy.ndarray

itur.utils.get_input_type(inpt)[source]¶

Return the type of the input.

If the input is an object of type Quantity, it returns the type of the associated value

Parameters:	inpt (object) – The input object.
Returns:	type – The type of the input.
Return type:	type

itur.utils.prepare_input_array(input_array)[source]¶

Format an array to be a 2-D numpy-array.

If the contents of input_array are 0-D or 1-D, it converts is to an array with at least two dimensions.

Parameters:	input_array (numpy.ndarray, sequence, or number) – The input value. It can be a scalar, 1-D array, or 2-D array.
Returns:	output_array – An 2-D numpy array with the input values
Return type:	numpy.ndarray

itur.utils.prepare_output_array(output_array, type_input=None)[source]¶

Format the output to have the same shape and type as the input.

This function is a generic wrapper to format the output of a function to have the same type as the input. ITU-Rpy makes extensive use of numpy arrays, but uses this function to return outputs having the same type that was provided in the input of the function.

itur.utils.prepare_quantity(value, units=None, name_val=None)[source]¶

Convert the input to the required units.

The function verifies that the input has the right units and converts it to the desired units. For example, if a value is introduced in km but posterior frequencies require this value to be in meters, this function would be called with units=u.m

Parameters:	value (astropy.units.Quantity, number, sequence, or np.ndarry) – The input value units (astropy.units) – Desired units of the output name_val (string) – Name of the variable (for debugging purposes)
Returns:	q – An numpy array with the values converted to the desired units.
Return type:	numpy.ndarray

itur.utils.compute_distance_earth_to_earth(lat_p, lon_p, lat_grid, lon_grid, method=None)[source]¶

Compute the distance between a point and a matrix of (lat, lons).

If the number of elements in lat_grid is smaller than 100,000, uses the WGS84 method, otherwise, uses the Haversine formula.

Parameters:	lat_p (number) – Latitude projection of the point P (degrees) lon_p (number) – Longitude projection of the point P (degrees) lat_grid (number, sequence of np.ndarray) – Grid of latitude points to which compute the distance (degrees) lon_grid (number, sequence of np.ndarray) – Grid of longitude points to which compute the distance (degrees)
Returns:	d – Distance between the point P and each point in (lat_grid, lon_grid) (km)
Return type:	numpy.ndarray

itur.utils.compute_distance_earth_to_earth_wgs84(lat_p, lon_p, lat_grid, lon_grid)[source]¶

Compute the distance between points using the WGS84 inverse method.

Compute the distance between a point (P) in (lat_p, lon_p) and a matrix of latitude and longitudes (lat_grid, lon_grid) using the WGS84 inverse method.

Parameters:	lat_p (number) – Latitude projection of the point P (degrees) lon_p (number) – Longitude projection of the point P (degrees) lat_grid (number, sequence of np.ndarray) – Grid of latitude points to which compute the distance (degrees) lon_grid (number, sequence of np.ndarray) – Grid of longitude points to which compute the distance (degrees)
Returns:	d – Distance between the point P and each point in (lat_grid, lon_grid) (km)
Return type:	numpy.ndarray

itur.utils.compute_distance_earth_to_earth_haversine(lat_p, lon_p, lat_grid, lon_grid)[source]¶

Compute the distance between points using the Haversine formula.

Compute the distance between a point (P) in (lat_s, lon_s) and a matrix of latitude and longitudes (lat_grid, lon_grid) using the Haversine formula.

Parameters:	lat_p (number) – Latitude projection of the point P (degrees) lon_p (number) – Longitude projection of the point P (degrees) lat_grid (number, sequence of np.ndarray) – Grid of latitude points to which compute the distance (degrees) lon_grid (number, sequence of np.ndarray) – Grid of longitude points to which compute the distance (degrees)
Returns:	d – Distance between the point P and each point in (lat_grid, lon_grid) (km)
Return type:	numpy.ndarray

References

This is based on the Haversine formula

itur.utils.regular_lat_lon_grid(resolution_lat=1, resolution_lon=1, lon_start_0=False, lat_min=-90, lat_max=90, lon_min=-180, lon_max=180)[source]¶

Build regular latitude and longitude matrices.

Builds a latitude and longitude coordinate matrix with resolution resolution_lat, resolution_lon.

Parameters:

resolution_lat (number) – Resolution for the latitude axis (deg)
resolution_lon (number) – Resolution for the longitude axis (deg)
lon_start_0 (boolean) – Indicates whether the longitude is indexed using a 0 - 360 scale (True) or using -180 - 180 scale (False). Default value is False

Returns:

lat (numpy.ndarray) – Grid of coordinates of the latitude point
lon (numpy.ndarray) – Grid of coordinates of the longitude point

itur.utils.elevation_angle(h, lat_s, lon_s, lat_grid, lon_grid)[source]¶

Compute the elevation angle between a satellite and a point on Earth.

Compute the elevation angle between a satellite located in an orbit at height h and located above coordinates (lat_s, lon_s) and a matrix of latitude and longitudes (lat_grid, lon_grid).

Parameters:	h (float) – Orbital altitude of the satellite (km) lat_s (float) – Latitude of the projection of the satellite (degrees) lon_s (float) – Longitude of the projection of the satellite (degrees) lat_grid (number, sequence of np.ndarray) – Grid of latitude points to which compute the elevation angle (degrees) lon_grid (number, sequence of np.ndarray) – Grid of longitude points to which compute the elevation angle (degrees)
Returns:	elevation – Elevation angle between the satellite and each point in (lat_grid, lon_grid) (degrees)
Return type:	numpy.ndarray

References

[1] http://www.propagation.gatech.edu/ECE6390/notes/ASD5.pdf - Slides 3, 4