Compute_Selection_By_Shell

Functions

int Compute_Selection_By_Shell (const char *action, const char *start_seg, int point_count, const HC_POINT *points, int face_list_length, const int *face_list)
 Forces a selection event between the supplied shell and a specified portion of a segment tree. More...
 
int Compute_Selection_By_Shell_With_Options (const char *action, const char *start_seg, int point_count, const HC_POINT *points, int face_list_length, const int *face_list, const char *options)
 Allows users to set additional criteria that should be considered when performing a selection event between the supplied shell and a specified portion of a segment tree. More...
 
int Compute_Selection_By_Swept_Shell (const char *action, const char *start_seg, HC_KEY shellkey, int number_of_sweeps, const float *matrices, const char *options)
 Forces a selection event between the volume created by a shell moving along a path and a specified portion of a segment tree. More...
 
int Compute_Selection_By_Swept_Shell2 (const char *action, const char *start_seg, HC_KEY shellkey, int number_of_sweeps, const float *matrices, const char *options, float *bounding_box)
 Similar to Compute_Selection_By_Swept_Shell(), but takes an extra parameter which receives a bounding box of the collision volume. More...
 
float Compute_Selection_Distance_By_Shell (const char *action, const char *start_seg, int pcount, const HC_POINT *points, int flist_length, const int *face_list, const char *options)
 Computes the closest distance between the specified shell and another geometric primitive within a HOOPS segment tree. More...
 
int DCompute_Selection_By_Shell (const char *action, const char *start_seg, int point_count, const HC_DPOINT *points, int face_list_length, const int *face_list)
 Similar to Compute_Selection_By_Shell(), but operates on double-precision data. More...
 
int DCompute_Selection_By_Shell_With_Options (const char *action, const char *start_seg, int point_count, const HC_DPOINT *points, int face_list_length, const int *face_list, const char *options)
 Similar to Compute_Selection_By_Shell_With_Options(), but operates on double-precision data. More...
 
int DCompute_Selection_By_Swept_Shell (const char *action, const char *start_seg, HC_KEY shellkey, int number_of_sweeps, const double *matrices, const char *options)
 Similar to Compute_Selection_By_Swept_Shell(), but operates on double-precision data. More...
 
int DCompute_Selection_By_Swept_Shell2 (const char *action, const char *start_seg, HC_KEY shellkey, int number_of_sweeps, const double *matrices, const char *options, double *bounding_box)
 Similar to Compute_Selection_By_Swept_Shell2(), but operates on double-precision data. More...
 
float DCompute_Selection_Distance_By_Shell (const char *action, const char *start_seg, int pcount, const HC_DPOINT *points, int flist_length, const int *face_list, const char *options)
 Similar to Compute_Selection_Distance_By_Shell(), but operates on double-precision data. More...
 

Detailed Description

Function Documentation

◆ Compute_Selection_By_Shell()

int Compute_Selection_By_Shell ( const char *  action,
const char *  start_seg,
int  point_count,
const HC_POINT *  points,
int  face_list_length,
const int *  face_list 
)

Forces a selection event between the supplied shell and a specified portion of a segment tree.

Parameters
action- One of "v", "^", "*", or "O". Action is compared against the selectability attribute settings as testing proceeds. See Set_Selectability() for a detailed explanation of actions.
start_seg- A segment in the tree at which to start selection testing.
point_count- Number of points in the shell that may enclose the points defined in points.
points- Vector of x-y-z triplets for the coordinates of the vertices to be used to build the shell. (A simple N x 3 array may also be used). Passed by reference always.
face_list_length- Size of the array of integers that defines the faces in face_list.
face_list- Encoded description of how to connect the points to build the faces of the shell (see Insert_Shell() ).
Returns
count - The number of objects that are touched by any part of the specified geometry.

DETAILS

This routine forces a selection event that is of a special form where the selection object is provided in object space. The routine operates with a volume defined by the specified geometry and can be used to implement collision detection operators. The process of performing the selection event and then querying the results is similar to the more standard selection events provided by Compute_Selection().

NOTES

Compute_Selection_By_Shell() only tests for shells that are intersecting (triangle collision). As a result, it will return zero when a shell is enclosed by the another shell.

To allow for fast computation of Compute_Selection_By_Shell(), shells from start_seg can be cross-referenced with spatial data structures (oct trees and/or bsp trees) that are retained between successive computations. To use this functionality, the selection event must be surrounded by calls to Begin_Shell_Selection() and End_Shell_Selection().

This function is identical to Compute_Selection_By_Key(), except that is does not require a shell to already exist.

RESTRICTIONS

  1. Use of Begin_Shell_Selection() constitutes a promise not to perform certain operations on anything contained in the segment tree until after the matching call to End_Shell_Selection(). See Begin_Shell_Selection() for details on the restrictions imposed.
  2. Only facetted geometries such as shells, meshes, NURBS surfaces, polygons, and polycylinders are selectable.
  3. If the shell has a hole, the hole is ignored for selection purposes. Visualize version 20 and above remove this restriction.

    See also
    Compute_Selection_By_Key, Compute_Selection, Begin_Shell_Selection, End_Shell_Selection

◆ Compute_Selection_By_Shell_With_Options()

int Compute_Selection_By_Shell_With_Options ( const char *  action,
const char *  start_seg,
int  point_count,
const HC_POINT *  points,
int  face_list_length,
const int *  face_list,
const char *  options 
)

Allows users to set additional criteria that should be considered when performing a selection event between the supplied shell and a specified portion of a segment tree.

Parameters
action- One of "v", "^", "*", or "O". Action is compared against the selectability attribute settings as testing proceeds. See Set_Selectability() for a detailed explanation of actions.
start_seg- A segment in the tree at which to start selection testing.
point_count- Number of points in the shell that may enclose the points defined in points.
points- Vector of x-y-z triplets for the coordinates of the vertices to be used to build the shell. (A simple N x 3 array may also be used). Passed by reference always.
face_list_length- Size of the array of integers that defines the faces in face_list.
face_list- Encoded description of how to connect the points to build the faces of the shell (see Insert_Shell() ).
options- A string through which a user can set options that affect the selections.
Returns
count - The number of objects that are touched by any part of the specified geometry.

DETAILS

This function performs exactly like Compute_Selection_By_Shell() except that the options string gives users more control over the internal selection algorithm.

The following choices for options are recognized:

clearance = x

A floating point value in object-relative units (oru) which defines how far away a shell can be from the input shell and still be regarded as "clashing". The default value is "clearance = 0".

tolerance = x

A floating point value in object-relative units (oru) that determines how far two shells can penetrate and still not be regarded as "clashing" (this is also know as a soft clash). A special value "tolerance = -1" specifies a tolerance based on the bounding boxes of the two shells involved in the clash. The value "tolerance = 0" indicates that penetrating geometry as well as coincident geometry (geometry that touches but does not penetrate) is considered to be a clash. The default value is "no tolerance" which means that coincident geometry will not cause a clash.

If the ‘tolerance’ value and/or selection shells ("probes") meet any of the following criteria, false positives or negatives may result: • The tolerance is much larger than the actual intersection of the shells. An example would be a shell that represents a thin plate or a thinly-walled tube, and the tolerance is larger than the thickness of the plate or tube. • Selection shells have vertices with complex intersections. • Selection shells have concavities, especially multiple adjacent concavities.

NOTE: If "clearance" is specified, any "tolerance" setting will be ignored.

See also
Compute_Swept_Shell, Compute_Swept_Shell_Along_Path

◆ Compute_Selection_By_Swept_Shell()

int Compute_Selection_By_Swept_Shell ( const char *  action,
const char *  start_seg,
HC_KEY  shellkey,
int  number_of_sweeps,
const float *  matrices,
const char *  options 
)

Forces a selection event between the volume created by a shell moving along a path and a specified portion of a segment tree.

Parameters
action- One of "v", "^", "*", or "O". Action is compared against the selectability attribute settings as testing proceeds. See Set_Selectability() for a detailed explanation of actions.
start_seg- A segment in the tree at which to start selection testing.
shellkey- Key to the shell that should be used for testing.
number_of_sweeps- The number of distinct steps in the sweep.
matrices- An array of matrices with each matrix having its own distinct 4x4 matrix.
options- A string through which a user can set options that affect the sweep.
Returns
count - The number of objects that are touched by any part of the specified geometry.

DETAILS

This routine forces a selection event that is of a special form wherein the selection object is provided in object space. The routine operates with a volume that is defined by a shell swept along a particular path and is often used to implement collision detection capabilities. The process of first performing the selection event, and then querying the results is similar to the more standard selection process provided by Compute_Selection(). To see what actual volume is used to perform the selection, users can call Compute_Swept_Shell_Along_Path().

Each matrix in the matrices array consists of 16 floating point values, and each matrix can contain both rotational and translational elements. The first modelling matrix in the array is not included in the sweep, but rather defines the initial starting position of the shell. Also, the modelling matrices are absolute and are not appended to the previous matrix.

Please note that the volume created by the sweep is not guaranteed to be watertight. Also, the interpolation between each step is linear and may not accurately reflect the desired movement. To reduce the errors, users should increase the number of steps in the sweep.

The options string can be used to control certain properties of the selection volume. The following choices for options are recognized:

generate front [= on | off]

When set, the swept shell(s) will include a copy of the original shell at the start location. This effectively closes the 'front' of the volume.

generate back [= on | off]

The swept shell will include a copy of the shell at the final location. This effectively closes the 'back' of the volume.

deviation = x

A radian value controlling the generation of silhouette edges. If the angle between a face plane and an edge vector is less than this angle (in radians) then the edge in question will be regarded as a silhouette edge. Increasing this value will improve quality but may impact performance.

last silhouette = ddd

Integer value that instructs the computation algorithm to include the silhouettes from ddd number of previous steps in the sweep. Increasing this value will improve quality but may impact performance.

The default setting for options is "generate front, generate back, deviation = 0, last silhouette = 1"

NOTES

To improve performance, shells from start_seg can be cross-referenced with spatial data structures (oct trees and/or bsp trees) that are retained between successive computations. To use this functionality, the selection event must be surrounded by calls to Begin_Shell_Selection() and End_Shell_Selection().

If only two matrices are provided and the second matrix only contains a translation component (all other entries are 0) the function Compute_Swept_Shell() is used for the sweeping operation, which can result in performance improvements. Otherwise the volume is calculated using Compute_Swept_Shell_Along_Path().

RESTRICTIONS

  • Only facetted geometries such as shells, meshes, NURBS surfaces, polygons, and polycylinders are selectable.
See also
Compute_Swept_Shell, Compute_Swept_Shell_Along_Path

◆ Compute_Selection_By_Swept_Shell2()

int Compute_Selection_By_Swept_Shell2 ( const char *  action,
const char *  start_seg,
HC_KEY  shellkey,
int  number_of_sweeps,
const float *  matrices,
const char *  options,
float *  bounding_box 
)

Similar to Compute_Selection_By_Swept_Shell(), but takes an extra parameter which receives a bounding box of the collision volume.

Parameters
action- One of "v", "^", "*", or "O". Action is compared against the selectability attribute settings as testing proceeds. See Set_Selectability() for a detailed explanation of actions.
start_seg- A segment in the tree at which to start selection testing.
shellkey- Key to the shell that should be used for testing.
number_of_sweeps- The number of distinct steps in the sweep.
matrices- An array of matrices with each matrix having its own distinct 4x4 matrix.
options- A string through which a user can set options that affect the sweep.
bounding_box- A bounding box of the collision volume, in the form of an array of six floats: (minx, miny, minz, maxx, maxy, maxz). Returned to user.
Returns
count - The number of objects that are touched by any part of the specified geometry.

◆ Compute_Selection_Distance_By_Shell()

float Compute_Selection_Distance_By_Shell ( const char *  action,
const char *  start_seg,
int  pcount,
const HC_POINT *  points,
int  flist_length,
const int *  face_list,
const char *  options 
)

Computes the closest distance between the specified shell and another geometric primitive within a HOOPS segment tree.

Parameters
action- One of "v", "^", "*", or "O". Action is compared against the selectability attribute settings as testing proceeds. See Set_Selectability() for a detailed explanation of actions.
start_seg- A segment in the tree at which to start selection testing.
pcount- Number of points contained in the points list.
points- Set of points that comprise the polyline or polygon used to compute the selection.
flist_length- The length of the face_list.
face_list- As described in the documentation of Insert_Shell() , An encoded description of how triangles should be combined to form faces, and the assignment of face identifiers.
options- A string containing a set of options to be applied to this distance calculation.
Returns
value - The distance from the object in the specified segment hierarchy to the provided shell. If nothing is found within the defined distance, -1 will be returned.

DETAILS

Developers often have the need to calculate the distance between a polygonal mesh and the rest of the 3D scene. Compute_Selection_Distance_By_Shell() allows developers to do this by allowing them to set criteria for their distance calculation and then providing the results back via the standard Show_Selection routines.

The options string consists of a comma separated list of options. Legal values for options include:

vector = (x, y, z)

If vector is supplied, then the return value is the exact distance that the shell would need to be moved along this vector before it hits a piece of geometry in the specified segment tree.

maximum distance = xxx oru

Objects that are further than this distance from every point in the selection shell are ignored. This option allows users to improve the performance of the computation by excluding certain objects from the calculation. The default setting is "no maximum distance".

Unlike the other selection routines, Compute_Selection_Distance_By_Shell() returns at most one object. To query this object, use the various Show_Selection routines.

RESTRICTIONS

Currently only shells within the specified segment hierarchy are considered for closest distance calculations.

See also
Compute_Selection_By_Key, Compute_Selection_By_Shell, Show_Selection_Source_Element, Show_Selection_Element, Compute_Selection, Show_Selection_Keys

◆ DCompute_Selection_By_Shell()

int DCompute_Selection_By_Shell ( const char *  action,
const char *  start_seg,
int  point_count,
const HC_DPOINT *  points,
int  face_list_length,
const int *  face_list 
)

Similar to Compute_Selection_By_Shell(), but operates on double-precision data.

Parameters
action- One of "v", "^", "*", or "O". Action is compared against the selectability attribute settings as testing proceeds. See Set_Selectability() for a detailed explanation of actions.
start_seg- A segment in the tree at which to start selection testing.
point_count- Number of points in the shell that may enclose the points defined in points.
points- Vector of x-y-z triplets for the coordinates of the vertices to be used to build the shell. (A simple N x 3 array may also be used). Passed by reference always.
face_list_length- Size of the array of integers that defines the faces in face_list.
face_list- Encoded description of how to connect the points to build the faces of the shell (see Insert_Shell() ).
Returns
count - The number of objects that are touched by any part of the specified geometry.

◆ DCompute_Selection_By_Shell_With_Options()

int DCompute_Selection_By_Shell_With_Options ( const char *  action,
const char *  start_seg,
int  point_count,
const HC_DPOINT *  points,
int  face_list_length,
const int *  face_list,
const char *  options 
)

Similar to Compute_Selection_By_Shell_With_Options(), but operates on double-precision data.

Parameters
action- One of "v", "^", "*", or "O". Action is compared against the selectability attribute settings as testing proceeds. See Set_Selectability() for a detailed explanation of actions.
start_seg- A segment in the tree at which to start selection testing.
point_count- Number of points in the shell that may enclose the points defined in points.
points- Vector of x-y-z triplets for the coordinates of the vertices to be used to build the shell. (A simple N x 3 array may also be used). Passed by reference always.
face_list_length- Size of the array of integers that defines the faces in face_list.
face_list- Encoded description of how to connect the points to build the faces of the shell (see Insert_Shell() ).
options- A string through which a user can set options that affect the selections.
Returns
count - The number of objects that are touched by any part of the specified geometry.

◆ DCompute_Selection_By_Swept_Shell()

int DCompute_Selection_By_Swept_Shell ( const char *  action,
const char *  start_seg,
HC_KEY  shellkey,
int  number_of_sweeps,
const double *  matrices,
const char *  options 
)

Similar to Compute_Selection_By_Swept_Shell(), but operates on double-precision data.

Parameters
action- One of "v", "^", "*", or "O". Action is compared against the selectability attribute settings as testing proceeds. See Set_Selectability() for a detailed explanation of actions.
start_seg- A segment in the tree at which to start selection testing.
shellkey- Key to the shell that should be used for testing.
number_of_sweeps- The number of distinct steps in the sweep.
matrices- An array of matrices with each matrix having its own distinct 4x4 matrix.
options- A string through which a user can set options that affect the sweep.
Returns
count - The number of objects that are touched by any part of the specified geometry.

◆ DCompute_Selection_By_Swept_Shell2()

int DCompute_Selection_By_Swept_Shell2 ( const char *  action,
const char *  start_seg,
HC_KEY  shellkey,
int  number_of_sweeps,
const double *  matrices,
const char *  options,
double *  bounding_box 
)

Similar to Compute_Selection_By_Swept_Shell2(), but operates on double-precision data.

Parameters
action- One of "v", "^", "*", or "O". Action is compared against the selectability attribute settings as testing proceeds. See Set_Selectability() for a detailed explanation of actions.
start_seg- A segment in the tree at which to start selection testing.
shellkey- Key to the shell that should be used for testing.
number_of_sweeps- The number of distinct steps in the sweep.
matrices- An array of matrices with each matrix having its own distinct 4x4 matrix.
options- A string through which a user can set options that affect the sweep.
bounding_box- The collision volume to select against, in the form of an array of six doubles: (minx, miny, minz, maxx, maxy, maxz).
Returns
count - The number of objects that are touched by any part of the specified geometry.

◆ DCompute_Selection_Distance_By_Shell()

float DCompute_Selection_Distance_By_Shell ( const char *  action,
const char *  start_seg,
int  pcount,
const HC_DPOINT *  points,
int  flist_length,
const int *  face_list,
const char *  options 
)

Similar to Compute_Selection_Distance_By_Shell(), but operates on double-precision data.

Parameters
action- One of "v", "^", "*", or "O". Action is compared against the selectability attribute settings as testing proceeds. See Set_Selectability() for a detailed explanation of actions.
start_seg- A segment in the tree at which to start selection testing.
pcount- Number of points contained in the points list.
points- Set of points that comprise the polyline or polygon used to compute the selection.
flist_length- The length of the face_list.
face_list- As described in the documentation of Insert_Shell() , An encoded description of how triangles should be combined to form faces, and the assignment of face identifiers.
options- A string containing a set of options to be applied to this distance calculation.
Returns
value - The distance from the object in the specified segment hierarchy to the provided shell. If nothing is found within the defined distance, -1 will be returned.