pe_geographic_densify_segment

Creates a densified geographic line between two geodetic points along a geodesic, loxodrome, or great elliptic

Usage syntax

int pe_geographic_densify_segment (double a, double e2, double lam1, double phi1, double lam2, double phi2, double coord[][2], double interval, int numpts, int geographic_linetype);

Parameters
a Semimajor axis of the spheroid
e2 Eccentricity squared of the spheroid
lam1 Longitude value of the first point
phi1 Latitude value of the first point
lam2 Longitude value of the second point
phi2 Latitude value of the second point
coord[][2] Array that will contain the densified set of points
interval Maximum distance between the new points
numpts Number of points in the coord array
geographic_linetype Type of line to use
Description

The pe_geographic_densify_segment function takes a spheroid and two geographic points and densifies the segment along a geodesic, a loxodrome, or a great elliptic. The geographic_linetype parameter specifies the type of line to use: geodesic, loxodrome, or great elliptic. A geodesic is the shortest distance between two points on a spheroid. A loxodrome is a line of equal bearing (a straight line in a Mercator projection). A great elliptic is the line created by the intersection of the spheroid surface with a plane formed by the center of the spheroid and two points on its surface. The valid line type values are:

   PE_LINETYPE_GEODESIC 0
PE_LINETYPE_LOXODROME 1
PE_LINETYPE_GREAT_ELLIPTIC 2

Beyond setting the type of line to densify, you can also specify how to densify the segment. You can set the distance between the points or the number of points in the line. If you set the interval to less than or equal to zero, the segment will be densified using the value of numpts. The number of points in the coord array will include the two endpoints. To densify the line using a distance, set the interval to a value greater than zero. In this case, the numpts parameter is the maximum number of points that can be in the coord array. If the interval value creates more points than the numpts value, the array will not be filled and pe_geographic_densify_segment returns the negative of the number of points that are required. The last point at lam2, phi2 may be closer than the interval distance to the preceding point.

Set e2 to zero to calculate distances on a sphere. The geographic coordinates are in radians. The semimajor axis (a) is usually given in meters. The interval is in the same units as the semimajor axis.

Returns

On success, pe_geographic_densify_segment returns the number of points in the array of points (in radians). If the parameters are defined such that the coord array is not large enough, the negative number of points required is returned. For example, if coord is allocated for 10 points, but the densified segment needs 12 points, -12 is returned.