PK_ERROR_code_t PK_TOPOL_range_local_vector
(
--- received arguments ---
PK_TOPOL_t topol, --- topological entity
PK_VECTOR_t vector, --- position vector
const PK_TOPOL_range_local_vector_o_t *options, --- options structure
--- returned arguments ---
int *const n_ranges, --- no. local minima
PK_range_1_r_t **const ranges --- range data
)
This function finds the local minimum separations between a topological
entity and a position.
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_local_vector will find the local closest approaches between
the topological entity topol and the position vector vector .
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.
An array of range data will be returned in ranges, this consists of an array
of structures of type PK_range_1_r_t, each of which contains a double
distance, which is the separation distance between the topological entity
and the position 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 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.
