 |
PK_TOPOL_range_geom |
|
PK_ERROR_code_t PK_TOPOL_range_geom
(
--- received arguments ---
PK_TOPOL_t topol, --- topological entity
PK_GEOM_t geom, --- geometrical entity
const PK_TOPOL_range_geom_o_t *options, --- option structure [PF]
--- returned arguments ---
PK_range_result_t *const range_result, --- whether range data returned
PK_range_2_r_t *const range --- range data
)
This function finds the global minimum/maximum distance between
a topology and a geometry.
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_TOPOL_range_geom will find the global minimum/maximum distance between
'topol' and 'geom'.
The following entity types are supported:
- 'topol': vertex, edge, face, body,
- 'geom': point, curve, surface.
The function returns 'range_result' which can be one of three values:
PK_range_result_found_c the distance has been successfully found.
PK_range_result_lower_c minimum/maximum distance does not satisfy the
supplied lower bound.
PK_range_result_upper_c minimum/maximum distance does not satisfy the
supplied upper bound.
If 'range_result' is equal to PK_range_result_found_c, then a range data will
be returned in 'range', this consists of a structure of type
PK_range_2_r_t, and contains a double 'distance', which is the
requested distance between the topological and geometrical entities provided,
and an array of two structures 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 the topology
supplied in 'topol' and in the second structure this
will contain the geometry supplied in 'geom'.
'sub_entity' : the topology of the lowest dimensionality which contains
the end position. e.g if a body is passed in as 'topol'
and the end position is found on a vertex then 'entity'
will return the body and 'sub_entity' will return the
vertex. If 'sub_entity' would be the same as 'entity'
then no 'sub_entity' will be returned.
If 'entity' is geometrical then no 'sub_entity' 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 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 |
|-----------|--------------|----------------------------|
| 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 |
|-----------|--------------|----------------------------|
| 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 - whether the point lies inside or outside
the body.
If 'entity' is a body and the point at the other end of
the separation lies inside the body, 'negative' will
return PK_LOGICAL_true, otherwise PK_LOGICAL_false will
be returned.
See Calculating minimum and maximum distance for more information.