PK_ERROR_code_t                 PK_BODY_pick_topols
(
--- received arguments ---
const int                       n_bodies,       --- number of bodies
const PK_PART_t                 bodies[],       --- body array
const PK_TRANSF_t              *body_transfs,   --- transformations
const PK_AXIS1_sf_t            *ray,            --- picking ray
const PK_BODY_pick_topols_o_t  *options,        --- control options

--- returned arguments ---
PK_BODY_pick_topols_r_t *const picked           --- picked entities
)


Pick entities from an array of body instances by their proximity to a line


Specific Errors:

        PK_ERROR_null_direction   near and far points are identical
        PK_ERROR_wrong_direction  near and far points are reversed




Overview
This function picks faces, edges and vertices from an array of instanced bodies
using a straight line ray. Faces are picked if they are intersected by the ray.
Edges & vertices are picked if they lie within a specified distance of the ray.


Body Instances
If the body_transfs argument is NULL, the ray is compared directly with
each of the n_bodies bodies. The bodies array must not contain duplicates.

If the body_transfs argument is not NULL, it refers to an array of n_bodies
PK_TRANSF_t entities. The ray is compared with the n_bodies bodies, with each
transformed by the corresponding entry in body_transfs. The bodies array may
contain duplicates. Instancing transforms may contain translation and rotation
but not perspective terms. If an instance does not need to be transformed, its
body_transfs entry can be set PK_ENTITY_null.


Options
The options structure defines which types of entity are picked, the maximum
distance allowed between an entity and the ray, controls on approximating
edge curves by polylines and the method by which picked edges and vertices
are sorted. It allows the picking ray to be constrained by near/far planes.