PK_ERROR_code_t               PK_FACE_instance_tools
(
--- received arguments ---
int                           n_target_faces, --- number of target faces (>0)
const PK_FACE_t               target_faces[], --- target faces
int                           n_tool_faces,   --- number of tool faces (>0)
const PK_FACE_t               tool_faces[],   --- tool faces to be instanced
int                           n_transforms,   --- number of transforms (>0)
const PK_TRANSF_t             transforms[],   --- instancing transforms
const PK_FACE_boolean_o_t    *options,

--- returned arguments ---
PK_FACE_inst_tools_r_t *const optional_returns
)


This function instances (creates and then booleans transformed copies of...)
a single tool body with a single target body, the boolean operation being a
unite or subtract. The tool and target body are each identified by a subset of
their faces, the subset being those faces which clash with the other body.


The tool body is not modified by the boolean, all instanced occurrences in the
resultant body are copies created during the operation.

This function will generally perform booleans involving identical tool bodies
considerably faster than other methods, this is however, dependent on the
intended configuration of target and instanced tools as indicated by the
configuration structure in the supplied options.

The function will perform optimally if the following fields of the
configuration structure have value PK_LOGICAL_true.

o no_tool_intersect
o no_loop_intersect
o identical_intersect
o one_in_all_in

Under these conditions the algorithm is able to perform a regular boolean
procedure for the first instanced tool and then create the other instances
by copying and transforming the surviving regions of this first instanced tool.

The optional_returns structure indicates which of the instanced tools appear
in the final result, this may be less than the n_transforms if some
of the instanced tools miss the target. Optionally information is supplied to
correlate new faces in the result with faces in the unmodified tool body.

The options and optional_returns structures are mandatory.

Restrictions

The target body may not be fragmented by the operation.

No target face may be split.

The identical_intersect field of the configuration structure indicates that
the intersection loops for one tool are identical to those for another.
If identical_intersect is set PK_LOGICAL_true then an additional requirement
for instancing is that the loops are also identically positioned on the
tool. Example, consider a set of parallel, solid cylinders united to an
inclined planar face forming elliptical intersection loops. Whilst the loops
would be identical ellipses, their relative positioning on each tool would
not be identical unless the vertical positioning of each cylinder was
adjusted according to its position on the incline, by a suitable transform.


errors
PK_ERROR_unsuitable_entity          arguments not of correct type.
PK_ERROR_tool_faces_many_bodies     tool faces are from more than one body.
PK_ERROR_targ_faces_many_bodies     target faces are from more than one body.
PK_ERROR_general_body               target or tool is a general body.
PK_ERROR_same_tool_and_target       target body cannot also be a tool body.
PK_ERROR_not_solid                  target or tool body is a sheet.
PK_ERROR_duplicate_array_item       duplicate face in target or tool array
PK_ERROR_instanced_tools            tool is instanced within an assembly.
PK_ERROR_invalid_bodies             boolean failure or invalid bodies.
PK_ERROR_non_manifold               result is non-manifold.
PK_ERROR_missing_geom               a topological entity lacks geometry.
PK_ERROR_cant_do_imprint            imprint failure
PK_ERROR_partial_coi_found          failure due to detection of partial
                                    coincidence.
PK_ERROR_partial_no_intersect       no imprinting in a local boolean.
PK_ERROR_boolean_failure            inconsistent arguments or internal error