PK_ERROR_code_t PK_EDGE_find_deviation
(
--- received arguments ---
PK_EDGE_t edge1, --- edge from which to find distances
PK_EDGE_t edge2, --- edge to which to find distance
int how_many, --- how many distances to find
--- returned arguments ---
int *const n_distances, --- number of distances returned
double **const distances, --- distances
PK_VECTOR_t **const edge1_vecs, --- points on edge1
PK_VECTOR_t **const edge2_vecs --- corresponding points on edge2
)
This function computes distances from edge1 to edge2.
Specific Errors:
PK_ERROR_bad_value Either one of the edges was null or they're both
the same
PK_ERROR_missing_geom One of the edges has no curve geometry on it
PK_ERROR_no_overlap The edges had no overlap
PK_ERROR_distancing_failed Determination of the distances not completed
because of algorithmic failure
PK_EDGE_find_deviation will provide distance samples between two edges received
in 'edge1' and 'edge2'. These distance samples are returned in three arrays
( 'distances', 'edge1_vecs', and 'edge2_vecs' ) whose corresponding entries
give a position on each edge and the measured distance between them.
One of the edges is selected as being apparently the more complicated one, and
regions on it where it 'overlaps' the other are determined. There may be zero,
one or two regions, and each region maybe extended or point-like. Within each
point-like overlap a single location on the preferred mroe complex edge is
chosen. For each extended region a number of locations on the more complicated
edge is chosen according to the value of the received argmument 'how_many'.
Once the locations are chosen on the more complex edge, distances are
determined from each of them to the closest points on the other edge. The value
of the 'how_many' produces three different kinds of sampling behaviour as
indicated below:
------------------------------------------------------------------------
| Value | |
| of | Behaviour |
|'how_many'| |
------------------------------------------------------------------------
| 0 | PK_EDGE_find_deviation chooses what it feels is the |
| | appropriate set of points in each region ( both in number |
| | and position. ) Distances are measured and returned at |
| | all these points. |
------------------------------------------------------------------------
| 1 | PK_EDGE_find_deviation chooses the same set of points as |
| | for the case 'how_many' == 0. However in this case only |
| | the pair of points producing the greatest distance is |
| | returned. |
------------------------------------------------------------------------
| N > 1 | For point-like regions a single location is chosen. The |
| | number of samples in each extended region is determined |
| | by dividing N by the number of such regions ( giving M |
| | samples per region say ). PK_EDGE_find_deviation then |
| | places M locations evenly in parameter space in each |
| | region on the more complex curve. Distances are then |
| | determined and returned from all chosen points. |
------------------------------------------------------------------------
The function assumes the two edges to present a reasonably parallel pairing
of curve geometries. Edges which differ significantly in direction can
produce non-intuitive results. Understanding these cases can be aided by
bearing in mind that the function seeks a collection of minimising, rather than
stationary, distances from ( 'fixed' ) points on one edge to the other.
