 |
PK_GEOM_range_vector_many |
|
PK_ERROR_code_t PK_GEOM_range_vector_many
(
--- received arguments ---
PK_GEOM_t geom, --- geometrical entity
int n_vectors, --- number of positions
const PK_VECTOR_t vectors[], --- position array
const PK_GEOM_range_vector_many_o_t *options, --- options structure
--- [PF]
--- returned arguments ---
PK_range_result_t range_results[], --- range status array
PK_range_1_r_t ranges[] --- range data array
)
This function finds the global minimum separations for each pairing of
the geometrical entity with one of the positions supplied.
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_bad_parameter bad parameter given (MILD)
PK_ERROR_no_closest_approach failed to find any closest approach (MILD)
The following geometry types are supported:
surface, curve and point.
The function returns two arrays 'range_results' and 'ranges' whose
corresponding entries provide a status and solution information for the
global minimum separation between the 'geom' and one of the 'vectors'
supplied. The arrays are ordered so that the global minimum separation for
any vector selected from the input array 'vectors' can be found in the
corresponding location in the output arrays. So the first element in
'range_results' and the first element in 'ranges' correspond to the first
element in 'vectors', the second element in 'range_results' and the second
element in 'ranges' correspond to the second element in 'vectors' and so on.
Each entry in the array 'range_results' can take one of four 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.
PK_range_result_not_found_c no separation has been found.
Entries in the 'range' array, are structures of type PK_range_1_r_t.
They contain meaningful information only in the case that the corresponding
entry in 'range_results' has value PK_range_result_found_c. Each PK_range_1_r_t
structure entry contains a double 'distance' which is the separation distance
between the geometrical entity in 'geom' and the corresponding vector in the
input array 'vectors'. It also contains a structure of type PK_range_end_t
which provides information on the end of the line of separation lying on the
geometrical entity 'geom' 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.
It is the application's responsibility to allocate arrays 'range_results' and
'ranges' with length 'n_vectors'.
See Calculating minimum and maximum distance for more information.