 |
CLPTEN |
CLPTEN
| Equivalent PK functions: |
PK_GEOM_range_array_vector PK_GEOM_range_vector PK_TOPOL_range_array_vector PK_TOPOL_range_vector PK_GEOM_range_local_vector PK_TOPOL_range_local_vector |
CLPTEN ( point, ents, nopts, iopts, optdta, mdist, elist, epoint, csparm,
==========================================================================
props, nprops, ifail )
======================
Finds the closest point on an entity to a given point.
Receives:
KI_vec_position point --- point
KI_tag_list_entity *ents --- 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> *elist --- entity list
KI_vec_position epoint --- point on entity
<KI_dbl> csparm[2] --- curve or surface parameters
KI_tag_list_int *props --- properties
<KI_int_nitems> *nprops --- no. of properties
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_closest_approach_failed failed to find closest approach
Description:
Given an entity or list of entities ('ents'), CLPTEN will determine an
entity point ('epoint') which is the minimum distance ('mdist') from the
received 'point'. Only one 'epoint' will be returned, regardless of how many
possible points achieve the minimum distance.
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 returned entity list ('elist') will contain two components:
- The first list component will be the tag of the (received) entity
upon which the solution was found to lie.
- The second list component will indicate a sub-topology upon which the
solution 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 a curve parameter or 2 surface parameters will be returned in
the 'csparm' array. This array is of length 2, but for the curve parameter
case the 2nd array entry should be ignored.
What parametrisation is used is firstly dependent upon the geometry of
the entity returned and secondly upon the geometry of the sub-topology (if
identified). 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). If supplied the
tolerance must not be less than the default value.
If both lower and upper bounds are supplied it is illegal for the lower bound
to be greater than the upper 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 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 | 3 reals: vector estimate |
| estimate | | |
| | | |
| 5. To supply a parameter | CLOPP1 | 1 or 2 reals: |
| estimate | | 1 curve |
| | | or 2 surface parameters |
| | | |
------------------------------------------------------------------------
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 along the entity from the solution point 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 'point' lies inside the body : RTCLND