| |
CLENEN |
| Equivalent PK functions: |
PK_GEOM_range PK_GEOM_range_array PK_TOPOL_range PK_TOPOL_range_array PK_GEOM_range_local PK_TOPOL_range_local |
CLENEN ( ents1, ents2, nopts, iopts, optdta, mdist, elist1, elist2, entpt1,
============================================================================
entpt2, parms1, parms2, props1, nprop1, props2, nprop2, ifail )
===============================================================
Finds the closest point between two entities/entity lists.
Receives:
KI_tag_list_entity *ents1 --- 1st entity/list of entities
KI_tag_list_entity *ents2 --- 2nd entity/list of entities
<KI_int_nitems> *nopts --- number of options
KI_cod_clop iopts[nopts] --- options
KI_tag_list_dbl optdta[nopts] --- option data
Returns:
<KI_dbl_distance> *mdist --- minimum distance
KI_tag_list_<entity> *elist1 --- entity list
KI_tag_list_<entity> *elist2 --- entity list
KI_vec_position entpt1 --- point on 1st entity
KI_vec_position entpt2 --- point on 2nd entity
<KI_dbl> parms1[2] --- parameter/s related to entpt1
<KI_dbl> parms2[2] --- parameter/s related to entpt2
KI_tag_list_int *props1 --- properties ( 1st entity)
<KI_int_nitems> *nprop1 --- no of properties in props1
KI_tag_list_int *props2 --- properties (2nd entity)
<KI_int_nitems> *nprop2 --- no of properties in props2
KI_cod_error *ifail --- failure indicator
Specific errors:
KI_missing_geom Topology without geometry supplied
KI_wrong_entity_in_list Unsupported entity type supplied in list
KI_wrong_entity Unsupported entity type supplied
KI_bad_option_data bad option data supplied
KI_request_not_supported topology/geometry not supported
KI_closest_approach_failed failed to find closest approach
Description:
CLENEN will find the closest approach between 'ent1' and ent2', where 'ent1'
and 'ent2' can either be single entities or lists of entities.
The following entity types are supported:
- Geometrical: point, curve, and surface.
- Topological: vertex, edge, face, and body.
Curves and surfaces must be legally attachable to edges and faces, and must
be G1 continuous.
The entities supplied must either all be geometry or all be topology.
The minimum distance ('mdist') will be returned together with a single pair of
solution points. The pair of solution points will be returned as two vectors
('entpt1' and 'entpt2'), the minimum distance being achieved between these
two vectors. Only one pair of solution points will be returned, regardless
of how many possible solution point pairs there are.
The entities and sub-topology upon which solution points lie will be
identified within the respective entity lists 'elist1' and 'elist2'.
These entity lists will be of length 2:
- The first list component will be the tag of the (received) entity
upon which the solution point was found to lie.
- The second list component will indicate a sub-topology upon which the
solution point was found to lie. This sub-topology will be either a
face, edge or vertex, belonging to a received entity. If the solution
does not lie on sub-topology a 'NULTAG' will be returned.
If either of the entities in the list has a tolerance associated with it, the
solution on that entity will only be accurate and unique up to the tolerance
of the entity.
Solution Parametrisation:
When appropriate curve or surface parameter/s will also be returned (in the
arrays 'parms1' and 'parms2'). What parametrisation is used is firstly
dependent upon the geometry of entity returned and secondly upon the
geometry of the sub-topology (if identified). Both arrays will be of length
2, but if curve parametrisation is used the 2nd array component should be
ignored.
The table below indicates what parametrisation is used and when:
----------------------------------------------------------------------
| Entity | Identified Sub-topology | Geometry used for |
| | | solution parametrisation |
|-------------|---------------------------|----------------------------|
| | | |
| 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 parametrisation functions ENPAPC, and ENPAPS.
Options:
Various options are available through the use of 'nopts' 'iopts' & 'optdta'.
'nopts' specifies the number of options requested, 'iopts' is an array of
option types, and 'optdta' is an array of lists of corresponding option data.
Some options are only available for restricted cases.
The following 3 options are available regardless of how many entities
or what entity types are supplied:
- An upper bound on the minimum distance to be computed may be supplied.
If such a bound is supplied the minimum distance achieved will only be
identified if it is less than the bound.
- A lower bound on the minimum distance. For this option, if the closest
approach between an 'entity' and 'point' is found to be less than this
bound, no solution will be determined and a token will be returned to
indicate that the minimum distance is less than this bound.
- A tolerance on the accuracy of the minimum distance measurement. This
will allow slacker computation of minimum distance, when the
default accuracy is not required. The default accuracy will be the
linear precision of the modeller (set up by SEMODP).
The following additional options will be available but only for limited
cases. These options must only be allowed to refer to a single entity,
and not a list of entities nor a single component of an entity list.
- For a single curve or edge, a curve parameter estimate may be
supplied.
- For a single surface or face, surface parameter estimates may be
supplied.
- For a single curve, surface, edge, or face, a position vector estimate
may be supplied. Such an estimate is expected to be on or close to the
entity.
Both parameter and position vector estimates cannot be supplied for an entity.
The use of any of the above estimates is not allowed if the minimum distance
computation involves a body (e.g. a face cannot be given estimates for
a face-body computation).
The table below details the tokens and data required for the options.
------------------------------------------------------------------------
| Option | Token | Option Data (real values) |
|---------------------------|--------- |---------------------------------|
| | | |
| 1. To supply an upper | CLOPUP | 1 real: the upper bound |
| distance bound | | |
| | | |
| 2. To supply a lower | CLOPLW | 1 real: the lower bound |
| distance bound | | |
| | | |
| 3. To supply a tolerance | CLOPTL | 1 real: the tolerance |
| | | |
| 4. To supply a pvec | CLOPPT | 4 reals: |
| estimate | | The 1st to indicate whether |
| | | the data applies to the 1st |
| | | or 2nd entity argument (must |
| | | equal 1.0 or 2.0) |
| | | The last 3 to indicate the |
| | | vector. |
| | | |
| 5. To supply a parameter | CLOPP1 | 1 or 2 reals: |
| estimate for the 1st | | 1 curve or 2 surface |
| entity | | parameter estimates |
| | | |
| 6. To supply a parameter | CLOPP2 | 1 or 2 reals: |
| estimate for the 2nd | | 1 curve or 2 surface |
| entity | | parameter estimates |
| | | |
------------------------------------------------------------------------
Properties:
A list of tokens, 'props' is returned to indicate the following:
- The solution as being a regional solution upon the entity (i.e it is
possible to move from solution point pair without the distance
changing) : RTCLRS
The identification of such a regional solution is not guaranteed.
- No solution being returned because the distance was found to be less
than the lower bound : RTCLLB
- No solution being returned because no distance was found to be less than
the upper bound : RTCLUB
- For a body only, the distance as being negative. The distance will be
classified as negative if the solution point on the other entity lies
inside the body : RTCLND