PK_ERROR_code_t             PK_TOPOL_range
(
--- received arguments ---
PK_TOPOL_t                  topol_1,        --- first topological entity
PK_TOPOL_t                  topol_2,        --- second topological entity
const PK_TOPOL_range_o_t   *options,        --- options structure

--- returned arguments ---
PK_range_result_t    *const range_result,   --- whether range data returned
PK_range_2_r_t       *const range           --- range data
)


This function finds the global minimum separation between two topological
entities.


Specific Errors:
    PK_ERROR_bad_option_data       bad option data given
    PK_ERROR_wrong_entity          given topology is of the wrong type
    PK_ERROR_missing_geom          given topology has missing geometry
    PK_ERROR_bad_parameter         bad parameter given
    PK_ERROR_no_closest_approach   failed to find closest approach




PK_TOPOL_range will find the global closest approach between topol_1 and
topol_2.

The following entity types are supported:
    - vertex, edge, face, and body.

The function also takes an options structure containing the following
optional additional information:

have_tolerance   : whether a tolerance value is provided.

tolerance        : a tolerance on the accuracy of the minimum distance
                     measurement. This will allow slacker computation of
                     minimum distance, when default accuracy is not required.
                     The default accuracy will be the linear precision
                     of the modeller.

bound            : option structure consisting of:
                     have_upper_bound: whether an upper bound is supplied.
                     `upper_bound      : an upper bound on the minimum
                                         distance to be computed.
                                         If supplied, the minimum distance
                                         achieved will only be identified
                                         if it is less than the bound.
                     have_lower_bound: whether a lower bound is supplied.
                     `lower_bound      : a lower bound on the minimum distance.
                                         For this option, if the closest
                                         approach between entities is found
                                         to be less than this bound, no
                                         solution will be determined.

guesses          : An array of two estimate structures, one for each end
                     of the separation, of the form:

                     type      : form of guess, either:
                                   PK_range_guess_no_c     : no guess
                                   PK_range_guess_param_c  : parametric guess
                                   PK_range_guess_vector_c : position guess
                     parameters: an array of up to 2 parameters
                     vector    : end position vector.

                     For an edge, a curve parameter estimate may be supplied.
                     For a face, surface parameter estimates may be supplied.
                     For an edge or face, a position vector estimate
                     may be supplied. Such an estimate is expected to
                     be on or close to the entity.
                     Both parameter and position vector estimates cannot
                     be supplied.



The function returns result which can be one of three values:
   PK_range_result_found_c      the separation has been successfully found.
   PK_range_result_lower_c      minimum separation is less than the provided
                                lower bound.
   PK_range_result_upper_c      no separation is less than the provided
                                upper bound.

If result is equal to PK_range_result_found_c, then a range data will
also be returned in range, this consists of a structure of type
PK_range_2_r_t, and contains a double distance, which is the
separation distance between the two topological entities provided, and
an array of two structures of type PK_range_end_t, which provide information
on each end of the line of separation as follows:

entity           : the entity at the end of the separation.
sub_entity       : the sub-entity at the end of separation (PK_ENTITY_null if
                     none is found).
vector           : end position.
parameters       : an array of two parameters of the end position holding
                     curve or surface parameter(s). Which parameterisation is
                     used is firstly dependent upon the geometry of the entity
                     returned and secondly upon the geometry of the sub-entity
                     (if identified).
                     If curve parameterisation is used the 2nd parameter should
                     be ignored.
                     The table below indicates which parameterisation is
                     used and when:

                      -------------------------------------------------------
                     |  Entity   |  Identified  |     Geometry used for      |
                     |           |  Sub-Entity  | solution parameterisation  |
                     |-----------|--------------|----------------------------|
                     |           |              |                            |
                     |  point    |     none     |          none              |
                     |  curve    |     none     |          curve             |
                     | surface   |     none     |         surface            |
                     |           |              |                            |
                     |  vertex   |     none     |          none              |
                     |           |              |                            |
                     |   edge    |     none     |     curve of the edge      |
                     |   edge    |    vertex    |     curve of the edge      |
                     |           |              |                            |
                     |    face   |     none     |    surface of the face     |
                     |    face   |     edge     |    surface of the face     |
                     |    face   |    vertex    |    surface of the face     |
                     |           |              |                            |
                     |    body   |     face     |    surface of the face     |
                     |    body   |     edge     |     curve of the edge      |
                     |    body   |    vertex    |          none              |
                     |           |              |                            |
                      -------------------------------------------------------

                     The curve and surface parameter values returned
                     will be the same as would be returned by the
                     parameterisation functions PK_CURVE_parameterise_vector
                     and PK_SURF_parameterise_vector.

region           : a logical value - whether the solution is regional. If
                     PK_LOGICAL_true, the solution is a regional solution upon
                     the entity (ie. it is possible to move from solution point
                     pair without the distance changing )
                     The identification of such a regional solution is not
                     guaranteed.

negative         : a logical value - for a body only, the distance as being
                     negative. If PK_LOGICAL_true the solution point on
                     the other entity lies inside the body