PK_ERROR_code_t PK_GEOM_range_vector
(
--- received arguments ---
PK_GEOM_t geom, --- geometrical entity
PK_VECTOR_t vector, --- position vector
const PK_GEOM_range_vector_o_t *options, --- options structure
--- returned arguments ---
PK_range_result_t *const range_result, --- if range data returned
PK_range_1_r_t *const range --- range data
)
This function finds the global minimum separation between a geometrical
entity and a position.
Specific Errors:
PK_ERROR_bad_option_data bad option data given
PK_ERROR_wrong_entity given entity is of the wrong type
PK_ERROR_missing_geom given entity has missing geometry
PK_ERROR_bad_parameter bad parameter given
PK_ERROR_no_closest_approach failed to find closest approach
PK_GEOM_range_vector will find the global closest approach between the
geometrical entity geom and a position vector vector.
The following entity types are supported:
- surface, curve and point.
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.
guess : An estimate structure, for the end of the separation
on the entity, 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 a curve, a curve parameter estimate may be supplied.
For a surface, surface parameter estimates may be
supplied.
For a curve or surface, 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_1_r_t, and contains a double distance, which is the
separation distance between the geometrical entity and the vector provided, and
a structure of type PK_range_end_t, which provides information on the
end of the line of separation on the entity 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 dependent upon the geometry of the entity
returned.
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 |
| | | |
-------------------------------------------------------
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
