PK_ERROR_code_t           PK_TOPOL_clash
(
--- received arguments ---
const int                 n_targets,    --- Number of target topologies
const PK_TOPOL_t          targets[],    --- Array of target topols
const PK_TRANSF_t         tf1[],        --- Transforms for targets
const int                 n_tools,      --- Number of tool topologies
const PK_TOPOL_t          tools[],      --- Array of tool topols
const PK_TRANSF_t         tf2[],        --- Transforms for tools
const PK_TOPOL_clash_o_t *options,      --- Options to be used

--- returned arguments ---
int                *const n_clash,      --- Number of clashes found
PK_TOPOL_clash_t  **const clashes       --- Returned array of clashes
)


This function clashes sets of topologies and returns the (list of)
body, face or edge pairs which clash; the test can be comprehensive, or just
find the first set, and can also return types of clashes.

This function supports body v body, body v face, and face v face clashing.




Terminology
Two entities have a "clash" if they have a one, two, or three-
dimensional overlap. Two objects are "clashed" together when we
inspect them to see if they have a clash.

The bounding topologies of the entities (faces in the case of bodies,
and edges in the case of faces) are returned; if there is no such
clash of bounding topologies, then the entities are examined to see
whether one lies within the other.

Bodies "abut" if they have faces which touch, but the bodies do not
share a common volume. Bodies "interfere" if they have faces which
cross. This implies that there is a common volume lying within each
body. While abutment is possible for real-world solid objects,
interference is not.

Faces "abut" if they have edges which touch, yet do not cross each
other, and there is no common area shared by the two faces. Faces
"interfere" if they cross each other, or have edges which cross, or
there is a common area to both faces.

Clashing topologies with different dimensions may also be considered;
for example, a three-dimensional cube may be clashed with a
two-dimensional sheet body. Here the distinction between abutment and
interference is made by considering "shared" points in space. If a
point in space exists within both bounding topologies of the two and
three-dimensional entities being clashed, then this clash is classed
as "interfere". If no such point in space exists, the clash is
classified as "abutment".


Returned information
If no clashes are found then n_clash is set to zero and clashes to NULL.

If clashes are found, then n_clash is the number of clashes found
and clashes points to a list of the clashes.

When clashing a face with a body, the types of clashes returned (if
requested) will be the same as those produced when clashing the
equivalent single-faced sheet body with the body.


Dealing with transforms
If you supply PK_ENTITY_null in place of a transform,
PK_TOPOL_clash substitutes an identity transform internally.

This can be used as a shortcut to supply identity transforms for
all the topologies in the target and/or tool lists. Set the
mul_target_tf (and/or mul_tool_tf) field in the options
structure to PK_LOGICAL_false (PK_TOPOL_clash_o_m will do this
for you) and supply PK_ENTITY_null as the first element of
tf1 (and/or tf2).  PK_TOPOL_clash will use the same transform
for each member of the list, and will substitute an identity
transform for the PK_ENTITY_null.

The tf1 and tf2 arguments may not be NULL pointers, and
perspective terms are not permitted in transforms supplied
to PK_TOPOL_clash.