struct PK_BODY_pick_topols_o_s
{
--- option structure version number
int o_t_version; --- version number
--- maximum of each type of topological entity to be picked (zero implies none)
int max_faces; --- max number of faces required
--- (1)
int max_edges; --- max number of edges required
--- (0)
int max_vertices; --- max number of vertices required
--- (0)
--- near/far culling
PK_LOGICAL_t near_plane; --- whether set
--- (PK_LOGICAL_false)
PK_LOGICAL_t far_plane; --- whether set
--- (PK_LOGICAL_false)
--- tolerances for the approximation of curves by a sequence of straight lines
PK_LOGICAL_t is_curve_chord_tol;
--- whether curve_chord_tol is set
--- (PK_LOGICAL_false)
double curve_chord_tol;
--- tolerance between curve/chord
--- (0.0)
PK_LOGICAL_t is_curve_chord_max;
--- whether curve_chord_max is set
--- (PK_LOGICAL_false)
double curve_chord_max;
--- maximum length of a chord
--- (0.0)
PK_LOGICAL_t is_curve_chord_ang;
--- whether curve_chord_ang is set
--- (PK_LOGICAL_false)
double curve_chord_ang;
--- max ang between adjacent chords
--- (0.0)
--- whether to ignore back facing faces (required if max_faces > 0)
PK_LOGICAL_t ignore_back_faces; --- face picking optimisation
--- (PK_LOGICAL_true)
--- max distance from edge to ray (required if max_edges > 0)
double max_edge_dist; --- max distance between ray/edges
--- (0.0)
--- max distance from vertex to ray (required if max_vertices > 0)
double max_vertex_dist; --- max dist between ray/vertices
--- (0.0)
--- points on near/far planes (required if using near_plane/far_plane options)
PK_VECTOR_t near_point; --- point on near_plane
--- (0.0, 0.0, 0.0)
PK_VECTOR_t far_point; --- point on far_plane
--- (0.0, 0.0, 0.0)
--- ordering method
PK_BODY_pick_method_t method; --- method of measuring pick dist
--- (PK_BODY_pick_axial_c)
--- ratio of radial:axial distance (required if method = PK_BODY_pick_ratio_c)
double ratio; --- bias when measuring pick dist
--- (0.0)
int n_geom_classes; --- specify the number of
--- geometry classes
--- (0)
PK_CLASS_t *geom_classes; --- specify the geometry classes
--- that can be picked
--- NULL
PK_pick_approximate_t pick_approx; --- approximate curves
--- or use accurate geometry
--- (PK_pick_approximate_yes_c)
};
typedef struct PK_BODY_pick_topols_o_s PK_BODY_pick_topols_o_t;
Controls picking of topological entities
The PK_BODY_pick_topols_o_t structure provides the following controls :
- the maximum number of each type of entity which can be picked
- the maximum separation allowed between the ray and candidate edges/vertices
- whether picking is performed using a bounded or an unbounded ray
- which chordal tolerances are used to approximate edge curves by polylines
- how distance is measured from candidate entities to the picking ray
- the option to specify which geometry classes can be picked
overview
The max_faces, max_edges and max_vertices options control which types of
entity can be picked and the maximum number of each type of entity which
can be returned.
Entities can be picked separately or together by setting one or more of
the max_faces, max_edges and max_vertices arguments to non-zero values.
The default is set by the PK_BODY_pick_topols_o_m macro with max_faces=1
and both max_edges and max_vertices=0 (i.e. set to pick the closest face).
max_faces
If max_faces > 0, this specifies the maximum number of faces which can
be picked. To be considered for picking, the intersection point between
a candidate face and the ray must lie within (or on) the face boundary.
If a face is intersected by the ray more than once, each intersection is
processed separately. Face picking is subject to the 'ignore_back_faces'
option.
max_edges
If max_edges > 0, this specifies the maximum number of edges which can be
picked. To be picked, the minimum distance between an edge and the ray must
be less than or equal to 'max_edge_dist' (this value must be specified).
The function calculates the minimum distance between the edge and the ray
(the 'hit distance') and records the position on the ray (the 'hit point')
at which this measurement was made.
If other points on the edge lie at the same distance from the ray, only
the first case is noted (an edge occurrence can only be picked once).
max_vertices
If max_vertices > 0, this specifies the maximum number of vertices which can
be picked. To be picked, the minimum distance between a candidate vertex and
the ray must be less than or equal to 'max_vertex_dist' (this value must be
specified).
The function calculates the minimum distance between the vertex and the ray
(the 'hit distance') and records the position on the ray (the 'hit point')
at which this measurement was made.
ignore_back_faces
The 'ignore_back_faces' setting is a performance option which is used when
picking faces (max_faces > 0). It enables Parasolid to optimise its search
by ignoring back-facing faces of solid bodies. Parasolid will only ignore
faces which are wholly facing backwards and it will not necessarily detect
all of such cases. This option has no effect when picking faces from sheet
bodies.
The PK_BODY_pick_topols_o_m macro sets the 'ignore_back_faces' option to
'PK_LOGICAL_true'. This setting is appropriate when picking the 'closest'
face (i.e. with max_faces = 1 )
If an application wishes to find all faces which are intersected by a ray
(i.e. max_faces > 1) and requires both forward and backward facing faces,
the value of 'ignore_back_faces' must be set to 'PK_LOGICAL_false'.
near and far planes
By default, the picking ray is defined as an unbounded line passing
through a point in a given direction. This can be constrained using
near/far planes (orthogonal to the ray) to define half-space regions.
If a near_plane is defined, only those entities lying behind the
plane can be picked. If an entity intersects the near plane, it
can only be picked if its 'hit point' lies behind the near plane.
If a far_plane is defined, only those entities lying in front of the
plane can be picked. If an entity intersects the far plane, it can
only be picked if its 'hit point' lies in front of the near plane.
Applications should avoid defining near/far planes which intersect face
and edge occurrences as this may yield (apparently) inconsistent results,
where some of the edges and faces which intersect the near/far planes
cannot be picked.
curve tolerance and approximation
The pick tolerance values control the approximation a curve by a sequence
of straight line chords. This polyline representation of a curve is used
when measuring distances to edges and checking whether the ray intersects
a face. When pick_approx option is set to PK_pick_approximate_no_c the
accurate geometry instead of polyline representation is used. This method
is slower. The default value of pick_approx is PK_pick_approximate_yes_c
and it is recommended for all interactive picking operations.
The tolerance values are defined by pair of PK_LOGICAL_t and double values.
The logical denotes whether the associated double defines a tolerance value.
If picking is being performed interactively, using rendered data which has
been generated by Parasolid, the curve tolerance arguments should be set to
the same values as used when the PK rendering functions were called. This
will allow Parasolid to pick entities using the same approximate polyline
form of curves as was used to construct the drawing.
In other cases, the curve tolerance arguments can be left as default values.
method
The 'method' argument is required when picking edges and vertices.
This determines how the returned edges/vertices are ordered.
- the method argument is not used when picking faces. These will always
be returned ordered by hit point, as if using 'PK_BODY_pick_axial_c'.
The possible settings for the 'method' argument are:
- PK_BODY_pick_radial_c
edges/vertices are ordered by hit distance measurement
- PK_BODY_pick_axial_c
edges/vertices are ordered by hit point (in the ray's axial direction)
- PK_BODY_pick_ratio_c'
edges/vertices are ordered by "pick distance" (using a combination
of the PK_BODY_pick_radial_c and PK_BODY_pick_axial_c methods)
The value of 'ratio' is used to vary the relative weightings given to
the radial and axial methods (its value must be positive or zero):
if ratio > 1.0 : pick_distance = hit_distance + rel_distance/ratio
if ratio = 1.0 : pick_distance = hit_distance + rel_distance
if ratio < 1.0 : pick_distance = hit_distance*ratio + rel_distance
The 'rel_distance' values for a set of entities E1, E2, E3 ...
are found by ordering the associated hit points P1, P2, P3 ...
selecting the 'front-most' point Pf
and calculating dist(Pf, P1), dist(Pf, P2), dist(Pf, P3) ...
where dist(Pi, Pj) is the distance from point Pi to Pj
If ratio is large, the effect is the same as using PK_BODY_pick_radial_c
If ratio is zero , the effect is the same as using PK_BODY_pick_axial_c
The PK_BODY_pick_topols_o_m macro initialises method to 'PK_BODY_pick_axial_c'.
This means that if edges and/or vertices are being picked at the same time as
faces, the returned entities will all be ordered by hit point. Typically this
means that entities are ordered by distance from an application's eye-point.
The 'PK_BODY_pick_radial_c' method is appropriate when firing a ray through a
'wire frame' representation of a body, where the 'hit-distance' from the ray
to candidate edges & vertices is more important than their relative distance
from the application's eye-point.
geometry classes
The option geom_classes allows the user to specify the classes of geometry
attached to topology that may be picked. The class types are passed in as an
array. At present only the surface classes for faces can be specified.
