Tmm_Elev_Profile_Get_With_Dist()
Note: Requires Terrain Modeling Module functionality
Abstract
Returns the terrain height at specified intervals along a path and the distance between points.
Syntax
Tmm_Elev_Profile_Get_With_Dist (point1_ptr, point2_ptr, meters_between_samples, lat_dist, lon_dist)
| Argument | Type | Description |
|---|---|---|
point1_ptr |
const TmmT_Position * |
pointer to the first position This argument uses the latitude and longitude fields of the TmmT_Position data structure to specify a point. The elevation field is not used. |
point2_ptr |
const TmmT_Position * |
pointer to the second position This argument uses the latitude and longitude fields of the TmmT_Position data structure to specify a point. The elevation field is not used. |
meters_between_samples |
float |
desired spacing of elevation values along the specified path, or TMMC_RESOLUTION_BEST (see Details). |
lat_dist |
double * |
pointer to an area to be filled with the north-south spacing (in degrees latitude) between successive points on the path |
lon_dist |
double * |
pointer to an area to be filled with the east-west spacing (in degrees longitude) between successive points on the path |
Return Value
TmmT_Elev_Profile *
Pointer to a terrain profile data structure.
Header
tmm.h
Example
elevation_profile_ptr = Tmm_Elev_Profile_Get_With_Dist (tx_pos_ptr, rx_pos_ptr, TMMC_RESOLUTION_BEST, lat_dist_ptr, lon_dist_ptr);
if ((elevation_profile_ptr == OPC_NIL) ||
(elevation_profile_ptr->data_status != TmmC_Elev_Data_All_Good))
{
/* No terrain */
/* Use freespace */
power_freespace (pkptr);
}
Details
This function allocates a new TmmT_Elev_Profile structure and fills it with an array of elevation values between the two requested points. The profile follows a great-circle path between the two points.
meters_between_samples specifies the desired distance between points on the profile path. This is treated as a minimum distance and will be increased if necessary to create intervals of equal size. If meters_between_samples is TMMC_RESOLUTION_BEST, the sample spacing will be the resolution of the terrain data.
The elevation profile is placed in a TmmT_Elev_Profile data structure, with the following contents:
Table 20: TmmT_Elev_Profile Data Structure
| Value | Type | Description |
|---|---|---|
reserved1 |
int |
not used |
point1 |
TmmT_Position |
the latitude and longitude of the first position. (The elevation value is 0.0.) |
point2 |
TmmT_Position |
the latitude and longitude of the second position. (The elevation value is 0.0.) |
distance_between_samples |
float |
the constant interval between elevation points, in meters |
data_status |
TmmT_Elev_Data_Status |
indicates if any elevation data was missing, by returning one of the constants in Table 88 “TMM Elevation Data Status Symbolic Constants“ on page 27. |
reserved2 |
float |
not used |
reserved3 |
float |
not used |
number_samples |
int |
the size of the profile_elevations array |
profile_elevations |
float * |
pointer to an array containing the elevation samples |
You must destroy this data structure using tmm_elev_profile_destroy() when it is no longer needed.
Purpose
This function returns the data necessary to specify a terrain profile along the line connecting two points, along with the latitudinal and longitudinal distances between successive points. Elevations are given at equally spaced intervals along the path.
Errors
- The terrain data directory (
<name>) is invalid. Unable to open terrain file.
Reference
- Use the function tmm_elev_profile_get() to obtain just an elevation profile, without lat_dist and lon_dist.
- Use the function tmm_elev_point_get() to obtain the height of the terrain at a specified point.
- Use the function tmm_elev_profile_destroy() to destroy the profile data array.