 |
PK_GEOM_range_array |
|
PK_ERROR_code_t PK_GEOM_range_array
(
--- received arguments ---
int n_geoms_1, --- no. entities in 1st array
const PK_GEOM_t geoms_1[], --- first geometrical array
int n_geoms_2, --- no. entities in 2nd array
const PK_GEOM_t geoms_2[], --- second geometrical array
const PK_GEOM_range_array_o_t *options, --- options structure [PF]
--- returned arguments ---
PK_range_result_t *const range_result, --- if range data returned
PK_range_2_r_t *const range --- range data
)
This function finds the global minimum/maximum separation between two arrays
of geometrical entities.
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 has 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_array will find the global global minimum/maximum distance
between the two arrays of geometrical entities 'geoms_1' and 'geoms_2'.
The following geometry types are supported:
- surface, curve and point.
The function returns 'range_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 'range_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 geometrical arrays of entities provided,
and an array of two structure of type PK_range_end_t, which provide
information on each end of the line of separation as follows:
'entity' : in the first structure this will contain a geometry
supplied in 'geoms_1' and in the second structure this
will contain a geometry supplied in 'geoms_2'.
'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.