 |
PK_TOPOL_range_local_vector |
|
PK_ERROR_code_t PK_TOPOL_range_local_vector
(
--- received arguments ---
PK_TOPOL_t topol, --- topological entity
--- [PF]
PK_VECTOR_t vector, --- position vector
const PK_TOPOL_range_local_vector_o_t *options, --- options structure
--- returned arguments ---
int *const n_ranges, --- no. local extrema
PK_range_1_r_t **const ranges --- range data
)
This function finds the local minimum/maximum separations between a topological
entity and a position.
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 topology is of the wrong type (MILD)
PK_ERROR_missing_geom given topology 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_local_vector will find local minima or maxima between
the topological entity 'topol' and the position vector 'vector'.
The following topology types are supported:
- vertex, fin, edge, face, and body.
Note that faces with surfaces of class PK_CLASS_mesh or their bodies are not
supported.
An array of range data will be returned in 'ranges', this consists of an array
of structures of type PK_range_1_r_t, each of which contains a double
'distance', which is the separation distance between the topological entity
and the position vector provided, and a structure of type PK_range_end_t,
which provides information on the end of the line of separation on the
entity as follows:
'entity' : the topology supplied in 'topol'.
'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 a fin is
identified as the 'sub_entity', the function will return
either the fin or the edge of the fin. This is dependent
on the option 'param_entity' in the option structure
PK_TOPOL_range_local_vector_o_t.
'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). Furthermore when the entity passed in is
a face, edge or fin, the parameterisation is also
dependent on what token (if any) is passed in via the
field 'param_entity' in the option structure
PK_TOPOL_range_local_vector_o_t.
If curve parameterisation is used the 2nd parameter should
be ignored.
When 'param_entity' is set to
PK_range_param_entity_topol_c, the following
parameterisation is used:
-------------------------------------------------------
| Entity | Identified | Geometry used for |
| | Sub-Entity | solution parameterisation |
|-----------|--------------|----------------------------|
| | | |
| vertex | none | none |
| | | |
| fin | none | curve of the fin |
| fin | vertex | curve of the fin |
| | | |
| 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 of the edge is the curve returned by
PK_EDGE_ask_geometry.
When 'param_entity' is set to PK_range_param_entity_sub_c:
-------------------------------------------------------
| Entity | Identified | Geometry used for |
| | Sub-Entity | solution parameterisation |
|-----------|--------------|----------------------------|
| | | |
| vertex | none | none |
| | | |
| fin | none | curve of the fin |
| fin | vertex | none |
| | | |
| edge | none | curve of the edge |
| edge | fin | curve of the fin |
| edge | vertex | none |
| | | |
| face | none | surface of the face |
| face | edge | curve of the edge |
| face | fin | curve of the fin |
| face | vertex | none |
| | | |
| body | face | surface of the face |
| body | edge | curve of the edge |
| body | fin | curve of the fin |
| body | vertex | none |
| | | |
-------------------------------------------------------
When the entity is a face, an edge can only be returned as
the identified sub-entity if it is accurate, in this case
the curve used for the parameterisation is the curve
attached to the edge. When the entity is an edge or a
body, the curve of the edge is the geometry or nominal
geometry attached to the edge. In all cases the geometry
will be returned by PK_EDGE_ask_geometry_nmnl.
If the entity is a face and the identified sub-entity is a
tolerant edge then the fin which belongs to both the face
and the edge that is nearest to the vector is returned.
If the entity is an edge or a body and the identified
sub-entity is a tolerant edge which has no nominal
geometry attached, then the primary fin of the edge is
returned. The primary fin is returned by
PK_EDGE_ask_first_fin.
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.
The function returns the distance between the vector and
a point on the geometric entity that the solution was
parameterised on. Therefore the distance may change when
a different solution parameterisation is employed.
For example, consider a vector on a face within tolerance
of an edge but not on one of the edge's fins. When the
face is passed in and 'param_entity' is set to
PK_range_param_entity_topol_c, the function will return a
zero distance as the solution is parameterised on the
face. However if 'param_entity' is set to
PK_range_param_entity_sub_c and the same face is passed
in, the function will return a non-zero distance as the
solution is parameterised on the edge's fin in the face.
When 'orthogonal_only' and 'param_entity' is set to
PK_LOGICAL_true and PK_range_param_entity_sub_c
respectively, the function gives primacy to
'orthogonal_only'. Therefore solutions will be
parameterised as described when 'param_entity' is set to
PK_range_param_entity_topol_c. If a solution can be
parameterised on the identified sub-entity without moving
the point on the body then an additional solution is
returned. The second solution is parameterised as
described above when 'param_entity' is set to
PK_range_param_entity_sub_c. Please note, the option
'orthogonal_only' controls the behaviour for edges and
faces only.
'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.