PK_VERTEX_optimise

PK_ERROR_code_t                    PK_VERTEX_optimise
(
--- received arguments ---
PK_VERTEX_t                        vertex,              --- vertex to be
                                                        --- optimised
const PK_VERTEX_optimise_o_t      *options,             --- option structure

--- returned arguments ---
PK_VERTEX_optimise_result_t *const result,              --- whether the vertex
                                                        --- has been modified
double                      *const achieved_deviation   --- best measured
                                                        --- deviation
)


Given a tolerant vertex, this function attempts to modify the position of
the vertex and the end points of any trimmed curves, such that the maximum
deviation falls within the given target value. It is also possible the vertex
tolerance will be modified or set to the optimised maximum deviation.




Definitions

Deviation             This is a measure of the distance from a vertex
                      to each of the curves of the edges or fins meeting
                      at the vertex.

                      In the case of trimmed curves this will be the
                      distance to the end the trimmed curve.

                      In the case of non-trimmed curves this will be the
                      distance to the closest point on the curve.

Maximum deviation     The maximum deviation is the greatest deviation
                      between the vertex and the curves of all fins or
                      edges meeting at the vertex. Although nominal
                      geometry is not used to calculate maximum deviation,
                      nominal geometry will be trimmed to maintain
                      consistency where necessary.


The function returns a 'result', of type PK_VERTEX_optimise_result_t
which has two values PK_VERTEX_optimise_success_c and
PK_VERTEX_optimise_failure_c.

PK_VERTEX_optimise_success_c indicates that the vertex position has been
modified (if required) such that the maximum deviation for the given vertex
satisfies the target value specified by the requested maximum deviation.
It does not necessarily indicate that the vertex tolerance has been modified
or set to the optimised maximum deviation (see Constraints).

PK_VERTEX_optimise_failure_c indicates that Parasolid was unable to find a new
position for the vertex such that the maximum deviation satisfies the target
value specified by the arguments.

The 'achieved_deviation' is always returned (regardless of whether the vertex
was optimised) and reflects the best measured deviation.


Constraints

Parasolid may not be able to modify the vertex tolerance to reflect the
optimised value for maximum deviation. For instance, a vertex is not allowed
a tolerance smaller in magnitude than any edges meeting at that vertex.

If constraints prevent Parasolid reducing the vertex tolerance to the
optimised maximum deviation, but still allows for a reduction, then Parasolid
will modify the vertex accordingly.