Calculating Minimum And Maximum Distance

28.1 Introduction

Parasolid provides a range of functionality that lets you calculate both the minimum distance (also known as closest approach) and the maximum distance between two different entities or groups of entities. Using this functionality, you can calculate the smallest or greatest distance between:

Two geometric entities or groups of geometric entities.
Two topological entities or groups of topological entities.
A topological entity and a geometric entity.
A group of topological entities and a group of geometric entities.

You can also find the minimum (but not maximum) distance between any entity or group of entities and a position or array of positions.

Note: This functionality offers partial support for facet geometry.

28.2 Functions available

This section gives a summary of the functions Parasolid provides for calculating the maximum and minimum distances between entities.

Use the following functions to find minimum and maximum distances between two entities. For convenience, these are referred to as the standard functions in subsequent sections.

Range function	Finds	Supported entities
PK_GEOM_range	The global minimum or maximum distances between two geometrical entities.	Point, curve, surface
PK_TOPOL_range	The global minimum or maximum distances between two topological entities.	Vertex, edge, face, body
PK_TOPOL_range_geom	The global minimum or maximum distances between a topological entity and a geometric entity.	Vertex, edge, face, body Point, curve, surface

Range function

Finds

Supported entities

PK_GEOM_range

The global minimum or maximum distances between two geometrical entities.

Point, curve, surface

PK_TOPOL_range

The global minimum or maximum distances between two topological entities.

Vertex, edge, face, body

PK_TOPOL_range_geom

The global minimum or maximum distances between a topological entity and a geometric entity.

Vertex, edge, face, body

Point, curve, surface

Use the following functions to find the minimum and maximum distances between two arrays of entities. For convenience, these are referred to as the array functions in subsequent sections.

Function	Finds	Supported entities
PK_GEOM_range_array	The global minimum or maximum distances between two arrays of geometrical entities.	Point, curve, surface
PK_TOPOL_range_array	The global minimum or maximum distances between two arrays of topological entities.	Vertex, edge, face, body
PK_TOPOL_range_geom_array	The global minimum or maximum distances between an array of topological entities and an array of geometric entities.	Vertex, edge, face, body Point, curve, surface
PK_ENTITY_range	The global minimum or maximum distances between two transformed arrays of entities. See Section 28.2.1, “Calculating the distance between transformed entity arrays” for more information.	Vertex, edge, face, body, surface, curve, point

Use the following functions to find the minimum distance between a position or array of positions and an entity or array of entities. For convenience, these are referred to as the vector functions in subsequent sections (the last two also fall into the category of array functions already mentioned).

Function	Finds	Supported entities
PK_GEOM_range_vector	The global minimum distance between a geometrical entity and a position.	Point, curve, surface
PK_GEOM_range_vector_many	The global minimum distances between a geometrical entity and an array of positions, one distance for each geometry/position pairing.	Point, curve, surface
PK_TOPOL_range_vector	The global minimum distance between a topological entity and a position.	Vertex, fin, edge, face, body
PK_GEOM_range_array_vector	The global minimum distance between an array of geometrical entities and a position.	Point, curve, surface
PK_TOPOL_range_array_vector	The global minimum distance between an array of topological entities and a position.	Vertex, fin, edge, face, body
PK_ENTITY_range_vector	The global minimum distance between a transformed array of entities and an array of positions. See Section 28.2.1, “Calculating the distance between transformed entity arrays” for more information.	Vertex, fin, edge, face, body, surface, curve, point

28.2.1 Calculating the distance between transformed entity arrays

You can calculate the distance between transformed arrays of entities without having to apply a transformation to each entity before the function call using PK_ENTITY_range and PK_ENTITY_range_vector functions,

The transforms for the input entities arrays are supplied via the tf (PK_ENTITY_range_vector only), tf_1 and tf_2 arguments. Only rigid transformations are supported (i.e reflections, translations, rotations or a combination of these).

If these arguments are set to PK_ENTITY_null, the entities in the array are not transformed.

[back to top]

28.3 Options available

The following table describes the options available to all of the functions that calculate either a global minimum or maximum distance.

Note: Not all options are available to all functions. Details are provided where relevant.

Option	Description
have_tolerance tolerance	By default, Parasolid performs maximum and minimum distance calculations to within Parasolid linear precision. By using these options, you can specify a tolerance on the accuracy of the calculation, allowing for a slacker computation of minimum or maximum distance. Using these options does not affect the accuracy of either: The entities you are measuring the distance between. That is, increasing the tolerance of the calculation does not mean that entities that are close to each other will be interpreted by the function as touching or intersecting. The precision of the data returned. Although the end points returned may not be optimal values for the distance calculation, they are still accurate to within Parasolid linear precision. Available in: all functions, except PK_ENTITY_range and PK_ENTITY_range_vector. Note: The `have_tolerance` option (PK_LOGICAL_false by default) should be used whenever you supply a `tolerance` .
bound	Lets you specify a maximum or minimum limit on the distance returned. This is a structure consisting of the following fields: `upper_bound/have_upper_bound` - defines an upper bound on the distance to be computed. If you supply this, the function only returns a distance if it is less than this value. `lower_bound/have_lower_bound` - defines a lower bound on the distance to be computed. If you supply this, the function only returns a distance if it is greater than this value. Available in: all functions. Note: If both lower and upper bounds are supplied, the lower bound must be less than the upper bound.
opt_level	Lets you specify the level of analysis that is used by the function to resolve closely separated local maxima or minima. You can choose between two values: PK_range_opt_performance_c - return a result that is optimised for performance. Using this value ensures that results are returned as quickly as possible, but in complex cases, a local minimum or maximum may be returned, rather than the global solution. This is the default. PK_range_opt_accuracy_c - return a result that is optimised for accuracy. In complex cases, using this value may return more accurate results than PK_range_opt_performance_c, but at the expense of performance. Available in: all functions, except PK_ENTITY_range and PK_ENTITY_range_vector. Note: This option is also available in functions for calculating local minimum distance, as described in Section 28.6, “Local minimum distance”.
guess guessesguesses_1guesses_2	You can sometimes improve Parasolid’s performance when calculating minimum or maximum distances if you can estimate where on the supplied entities the end points of that distance are likely to be found. You can use these options to supply parameters that you think are near to the end points of the maximum or minimum distance. See Section 28.4, “Using estimates to improve performance” for more information. Available in: all functions except PK_GEOM_range_array, PK_TOPOL_range_array and PK_TOPOL_range_geom_array.
range_type	Specifies whether to find the global minimum or the global maximum distance between the given entities. This can be one of the following: PK_range_type_minimum_c: find the minimum distance (the default). PK_range_type_maximum_c: find the maximum distance. Available in: all functions except vector functions.
param_bound param_boundsparam_bounds_1param_bounds_2	Specifies bounds for any geometrical entities. You supply bounds using a PK_range_param_bound_t structure, which should include either: An interval, if the unbounded geometry is a curve A uv-box, if the unbounded geometry is a surface. You can supply bounds for both bounded and unbounded geometrical entities. For a bounded entity, this just limits the range of interest for that entity. For an unbounded entity, this guarantees that maximum distance calculations do not return infinite values. Available in: all standard and array functions that involve at least one geometrical entity. Note: You must use this option if you are calculating maximum distances using at least one unbounded geometry; failure to do this results in a function error.
`param_entity`	Specifies whether to return a vector and parameter on the `sub_entity` in the returned range_data, when the point of minimum separation between the topological entity and a vector is found on the sub-entity.This option will only affect the behaviour of functions when a face, edge or fin is passed in. Default: PK_range_param_entity_topol_c Available in: all vector functions that involve at least one topological entity and PK_ENTITY_range. Note: This option is also available in functions for calculating local minimum and maximum distance between a topological entity and a position, as described in Section 28.6, “Local minimum distance”.

Option

Description

have_tolerance

tolerance

By default, Parasolid performs maximum and minimum distance calculations to within Parasolid linear precision. By using these options, you can specify a tolerance on the accuracy of the calculation, allowing for a slacker computation of minimum or maximum distance.

Using these options does not affect the accuracy of either:

The entities you are measuring the distance between. That is, increasing the tolerance of the calculation does not mean that entities that are close to each other will be interpreted by the function as touching or intersecting.
The precision of the data returned. Although the end points returned may not be optimal values for the distance calculation, they are still accurate to within Parasolid linear precision.

Available in: all functions, except PK_ENTITY_range and PK_ENTITY_range_vector.

Note: The


have_tolerance

option (PK_LOGICAL_false by default) should be used whenever you supply a


tolerance

bound

Lets you specify a maximum or minimum limit on the distance returned. This is a structure consisting of the following fields:

upper_bound/have_upper_bound - defines an upper bound on the distance to be computed. If you supply this, the function only returns a distance if it is less than this value.
lower_bound/have_lower_bound - defines a lower bound on the distance to be computed. If you supply this, the function only returns a distance if it is greater than this value.

Available in: all functions.

Note: If both lower and upper bounds are supplied, the lower bound must be less than the upper bound.

opt_level

Lets you specify the level of analysis that is used by the function to resolve closely separated local maxima or minima. You can choose between two values:

PK_range_opt_performance_c - return a result that is optimised for performance. Using this value ensures that results are returned as quickly as possible, but in complex cases, a local minimum or maximum may be returned, rather than the global solution. This is the default.
PK_range_opt_accuracy_c - return a result that is optimised for accuracy. In complex cases, using this value may return more accurate results than PK_range_opt_performance_c, but at the expense of performance.

Available in: all functions, except PK_ENTITY_range and PK_ENTITY_range_vector.

Note: This option is also available in functions for calculating local minimum distance, as described in Section 28.6, “Local minimum distance”.

guess

guessesguesses_1guesses_2

You can sometimes improve Parasolid’s performance when calculating minimum or maximum distances if you can estimate where on the supplied entities the end points of that distance are likely to be found. You can use these options to supply parameters that you think are near to the end points of the maximum or minimum distance.

See Section 28.4, “Using estimates to improve performance” for more information.

Available in: all functions except PK_GEOM_range_array, PK_TOPOL_range_array and PK_TOPOL_range_geom_array.

range_type

Specifies whether to find the global minimum or the global maximum distance between the given entities. This can be one of the following:

PK_range_type_minimum_c: find the minimum distance (the default).
PK_range_type_maximum_c: find the maximum distance.

Available in: all functions except vector functions.

param_bound

param_boundsparam_bounds_1param_bounds_2

Specifies bounds for any geometrical entities. You supply bounds using a PK_range_param_bound_t structure, which should include either:

An interval, if the unbounded geometry is a curve
A uv-box, if the unbounded geometry is a surface.

You can supply bounds for both bounded and unbounded geometrical entities.

For a bounded entity, this just limits the range of interest for that entity.
For an unbounded entity, this guarantees that maximum distance calculations do not return infinite values.

Available in: all standard and array functions that involve at least one geometrical entity.

Note: You must use this option if you are calculating maximum distances using at least one unbounded geometry; failure to do this results in a function error.

param_entity

Specifies whether to return a vector and parameter on the sub_entity in the returned range_data, when the point of minimum separation between the topological entity and a vector is found on the sub-entity.This option will only affect the behaviour of functions when a face, edge or fin is passed in. Default: PK_range_param_entity_topol_c

Available in: all vector functions that involve at least one topological entity and PK_ENTITY_range.

Note: This option is also available in functions for calculating local minimum and maximum distance between a topological entity and a position, as described in Section 28.6, “Local minimum distance”.

[back to top]

28.4 Using estimates to improve performance

The guess , guesses , guesses_1 and guesses_2 options (the name is different depending on which function you call it from) let you provide either a parameter or a vector that represents a place on the entity that you believe is close to an end position of the minimum or maximum distance on that entity. If you can provide such estimates, it can improve Parasolid’s performance when using any of these functions.

Note: Where parameter information is known, a parameter-space guess is recommended over a vector guess. Internally, any vector guess is converted to a parameter guess by projecting the vector to the surface. This requires extra computation time and vector positions near complex areas of the surfaces (e.g high-curvature) could potentially result in UV guesses that lead to sub-optimal solutions.

Figure 28-2 shows a simple example in which PK_GEOM_range is used to calculate the minimum distance between two curves. For each curve, the parameter highlighted is passed to the function as an estimate, using the guesses option. PK_GEOM_range then starts looking for a solution from the supplied parameter, thereby improving performance.

Figure 28-2 Providing estimates when calculating minimum distance between two curves

To use this option, you provide a separate estimate for any entity that you are measuring the distance between as follows:

For standard functions you can either provide one or two estimates. Performance is likely to be improved most if you can provide two estimates. The option name is guesses
For the array function PK_ENTITY_range you can only provide an estimate for a single entity input. The option names are guesses_1 and guesses_2
For vector functions (except for PK_GEOM_range_vector_many) you only provide a single estimate, since providing an estimate for a known vector would be meaningless. The option name is guess .
For PK_GEOM_range_vector_many you provide an array of estimates, one for each position supplied to the function. The option name is guesses .

Note: You cannot provide estimates for any of the following array functions: PK_GEOM_range_array, PK_TOPOL_range_array, and PK_TOPOL_range_geom_array. If you are using array functions to measure distances, and you have enough information to provide an estimate, then you should use the corresponding standard function instead (for example, use PK_GEOM_range rather than PK_GEOM_range_array).

You provide each estimate using a PK_range_guess_t structure. This contains the following fields:

Field	Description
type	The type of data you are supplying for your estimate. This is one of the following: PK_range_guess_no_c: no estimate (the default) PK_range_guess_param_c: a parameter PK_range_guess_vector_c: a position
parameters	If `type` is PK_range_guess_param_c, this field contains the corresponding parameter information. It is an array containing up to two parameters. If you are supplying data for a curve or edge, supply a curve parameter in `parameters[0]` . If you are supplying data for a surface or face, supply a surface parameter using both `parameters[0]` and `parameters[1]` .
vector	If `type` is PK_range_guess_vector_c, this field contains the corresponding position. You can supply a vector if the solution is to be found on an edge of a face. Note: You should not supply both parameter and position estimates within a single PK_range_guess_t structure.

Field

Description

type

The type of data you are supplying for your estimate. This is one of the following:

PK_range_guess_no_c: no estimate (the default)
PK_range_guess_param_c: a parameter
PK_range_guess_vector_c: a position

parameters

If type is PK_range_guess_param_c, this field contains the corresponding parameter information. It is an array containing up to two parameters.

If you are supplying data for a curve or edge, supply a curve parameter in parameters[0] .
If you are supplying data for a surface or face, supply a surface parameter using both parameters[0] and parameters[1] .

vector

If type is PK_range_guess_vector_c, this field contains the corresponding position. You can supply a vector if the solution is to be found on an edge of a face.

Note: You should not supply both parameter and position estimates within a single PK_range_guess_t structure.

Note: Estimates are not allowed for calculations involving bodies. For example, if you are looking for the minimum distance between a face and a body, you cannot provide an estimate for the body.

[back to top]

28.5 Results returned

The following tables provides a summary of the data returned by the maximum/minimum distance functions:

All functions except PK_ENTITY_range and PK_ENTITY_range_vector have the following results structure:

Field	Description
range_result	A token that indicates the result of the operation. This is one of the following values: PK_range_result_found_c: a minimum or maximum distance was successfully found. PK_range_result_lower_c: no distance greater than the `lower_bound` provided was found. PK_range_result_upper_c: no distance less than the `upper_bound` provided was found. PK_range_result_not_found_c: failed to identify the separation
range	A structure that contains the computed `distance` , together with details about the end positions that describes where the distance lies. The exact structure used depends on the calling function: For all vector functions, a PK_range_1_r_t is returned which contains details about the `end` position on the single entity received by the vector function. For all other functions, a PK_range_2_r_t is returned which contains details about the `ends` of both entities received by the function. The details for each end position are contained in a PK_range_end_t structure. A description of the information that is returned for each function is available in the header documentation for the relevant function: see the PK Interface Programming Reference Manual for more information.

Field

Description

range_result

A token that indicates the result of the operation. This is one of the following values:

PK_range_result_found_c: a minimum or maximum distance was successfully found.
PK_range_result_lower_c: no distance greater than the lower_bound provided was found.
PK_range_result_upper_c: no distance less than the upper_bound provided was found.
PK_range_result_not_found_c: failed to identify the separation

range

A structure that contains the computed distance , together with details about the end positions that describes where the distance lies.

The exact structure used depends on the calling function:

For all vector functions, a PK_range_1_r_t is returned which contains details about the end position on the single entity received by the vector function.
For all other functions, a PK_range_2_r_t is returned which contains details about the ends of both entities received by the function.

The details for each end position are contained in a PK_range_end_t structure. A description of the information that is returned for each function is available in the header documentation for the relevant function: see the PK Interface Programming Reference Manual for more information.

Note: For PK_GEOM_range_vector_many, an array of range results and ranges is returned, one for each minimum distance calculated (and hence each position received by the function). Consequently, the returned fields for this function are called


range_results

and


ranges

respectively.

PK_ENTITY_range and PK_ENTITY_range_vector functions have a results structure with the following fields:

Field	Description
`results`	A token that indicates the result of the operation. This is one of the following values: PK_range_result_found_c: a minimum or maximum distance was successfully found. PK_range_result_lower_c: no distance greater than the `lower_bound` provided was found. PK_range_result_upper_c: no distance less than the `upper_bound` provided was found. PK_range_result_not_found_c: failed to identify the separation.
`distances`	Double array that indicates the separation distance between entities.
`ends`	The details for each end position that describes where the `distance` lies are contained in a PK_ENTITY_range_end_t structure. A description of the information that is returned for each function is available in the header documentation for the relevant function: see the PK Interface Programming Reference Manual for more information.

Field

Description

results

A token that indicates the result of the operation. This is one of the following values:

PK_range_result_found_c: a minimum or maximum distance was successfully found.
PK_range_result_lower_c: no distance greater than the lower_bound provided was found.
PK_range_result_upper_c: no distance less than the upper_bound provided was found.
PK_range_result_not_found_c: failed to identify the separation.

distances

Double array that indicates the separation distance between entities.

ends

The details for each end position that describes where the distance lies are contained in a PK_ENTITY_range_end_t structure. A description of the information that is returned for each function is available in the header documentation for the relevant function: see the PK Interface Programming Reference Manual for more information.

[back to top]

28.6 Local minimum distance

In addition to finding the global minimum distance between two entities, Parasolid provides support for finding local minimum distance. The following functions are available for this purpose:

Function	Finds	Supported entities
PK_GEOM_range_local	The local minimum distance between two geometrical entities	Point, curve, surface
PK_TOPOL_range_local	The local minimum distance between two topological entities	Vertex, edge, face, body
PK_GEOM_range_local_vector	The local minimum distance between a geometrical entity and a position	Point, curve, surface
PK_TOPOL_range_local_vector	The local minimum or maximum distance between a topological entity and a position	Vertex, fin, edge, face, body

See the PK Interface Programming Reference Manual for more information.

[back to top]

<<< Mass Properties

Chapters

Clash Detection Of Bodies >>>

Contents

28.1 Introduction

28.2 Functions available

28.2.1 Calculating the distance between transformed entity arrays

28.3 Options available

28.4 Using estimates to improve performance

28.5 Results returned

28.6 Local minimum distance