| |
CLENEX |
| 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 |
CLENEX ( ents1, ents2, nopts, iopts, optdta, nmins, min_dists, elists1,
========================================================================
elists2, entpts1, entpts2, parms1, parms2, props1, nprops1, props2,
====================================================================
nprops2, 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_int_nitems> *nmins --- number of minima returned
<KI_tag_list_dbl> *min_dists --- distances
<KI_tag_list_<list>> *elists1 --- lists of entities
<KI_tag_list_<list>> *elists2 --- lists of entities
<KI_tag_list_list> *entpts1 --- point on 1st entity
<KI_tag_list_list> *entpts2 --- point on 2nd entity
<KI_tag_list_list> *parms1 --- parameter/s related to entpt1
<KI_tag_list_list> *parms2 --- parameter/s related to entpt2
<KI_tag_list_<list>> *props1 --- properties ( 1st entity)
<KI_tag_list_int> *nprops1 --- no of properties in props1
<KI_tag_list_<list>> *props2 --- properties (2nd entity)
<KI_tag_list_int> *nprops2 --- 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:
CLENEX will find global or local closest approaches between 'ents1' and ents2'.
Where a single global closest approach is requested 'ents1' and 'ents2' can
either be single entities or lists of entities. If all local closest approaches
are required then both 'ents1' and 'ents2' must be single 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 function returns the number of closest approaches found and collection
of lists all of the same length. Taken together the n'th entries of these
list form a description of the n'th closest approach found, as follows:
The entry from the list 'min_dists' is a real value for the distance of the
closest approach, and 'entpts1' and 'entpts2' corresponding entries hold the
points between which the closest approach is achieved (as lists of 3 reals).
The entries in 'elists1' and 'elists2' are lists, of length 2, which identify
the entities and sub-topology upon which those solution points lie. These lists
will be structured as follows:
- 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 is provided by the entries in the 'parms1' and
'parms2' lists when appropriate. These entries are real lists of length 2
holding curve or surface parameter/s. Which parametrisation is used is firstly
dependent upon the geometry of entity returned and secondly upon the
geometry of the sub-topology (if identified). If curve parametrisation is
used the 2nd list 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.
Properties:
Properties of the closest approach are returned through the entries in the
'props1' and 'props2' lists. Each entry is a list of tokens ( of variable
lengths given by the entries in 'nprops1' and 'nprops2' ). These properties
and their tokens are as follows:
- RTCLRS: The solution is a regional solution upon the entity (i.e it
is possible to move from solution point pair without the distance
changing )
The identification of such a regional solution is not guaranteed.
- RTCLND: 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
In the case that there are no solutions, i.e. upper or lower bounds (see below)
have been set that rule out all closest approaches, 'nmins' will
be set to 0 and the lists 'props1' and 'props' will be of length 1. The
only entry in these lists will be a list holding a single token indicating
why no solutions could be found:
- RTCLLB No solution being returned because the distance was found to
be less than the lower bound
- RTCLUB: No solution being returned because no distance was found to be
less than the upper bound
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 option, 'CLOPTL', is available under all circumstances:
- 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).
An option, 'CLOPFA', is available to request that all local closest approaches
should be returned. At present this option is incompatible with all the other
options mentioned below. It is also only available in the case that 'ents1'
and 'ents2' are single entities.
If the option for searching for all closest approaches is omitted, then
the following options are available. Some of these do have restrictions of
their own.
The following 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 entities 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.
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 |
| | | |
| 7. To request that all | CLOPFA | No data required. |
| local closest | | |
| approaches be | | |
| returned | | |
| | | |
------------------------------------------------------------------------