 |
PK_GEOM_range_local_vector |
|
PK_ERROR_code_t PK_GEOM_range_local_vector
(
--- received arguments ---
PK_GEOM_t geom, --- geometrical entity
--- [PF]
PK_VECTOR_t vector, --- position vector
const PK_GEOM_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 geometrical
entity and a position.
This function offers partial support for facet geometry [PF]
Specific Errors:
PK_ERROR_bad_option_data bad option data given (MILD)
PK_ERROR_wrong_entity given entity is of the wrong type (MILD)
PK_ERROR_missing_geom given entity given missing geometry (MILD)
PK_ERROR_bad_parameter bad parameter given (MILD)
PK_ERROR_no_closest_approach failed to find closest approach (MILD)
PK_GEOM_range_local_vector will find the local closest approaches between
the geometrical entity 'geom' and a position vector 'vector'.
The following geometry types are supported:
- surface, curve and point.
Note that surfaces of class PK_CLASS_mesh are not supported.
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 geometrical
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 geometry supplied in 'geom'.
'sub_entity' : not applicable, PK_ENTITY_null will be returned.
'vector' : the end position on 'entity'.
'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' : not applicable, PK_LOGICAL_false will be returned.
See Calculating minimum and maximum distance for more information.