PK_ERROR_code_t                        PK_FACE_output_surf_trimmed
(
--- received arguments ---
PK_FACE_t                              face,         --- face
const PK_FACE_output_surf_trimmed_o_t *options,      --- options structure

--- returned arguments ---
PK_SURF_t                       *const surf,         --- surface
PK_LOGICAL_t                    *const sense,        --- which side of surface
PK_SURF_trim_data_t             *const trim_data,    --- trim data
PK_GEOM_t                      **const geoms,        --- points and curves
PK_INTERVAL_t                  **const intervals,    --- geom intervals
PK_TOPOL_t                     **const topols        --- topologies
)


This function returns a trimmed surface representation of the given face.


Specific Errors:
    PK_ERROR_missing_geom            given face has no surface
    PK_ERROR_bad_option_data         option data incorrect
    PK_ERROR_tolerances_too_tight    curve tolerance too tight
    PK_ERROR_trim_loop_degenerate    trimming loop degenerate
    PK_ERROR_cant_make_bspline       failed to make equivalent bspline surface
    PK_ERROR_cant_make_trimmed_sf    failed to make trimmed surface


See the documentation for PK_FACE_output_surf_trimmed_o_t for a description
of the options.


The Trimmed Surface Representation returned:

A trimmed surface represents a bounded region of a parameterised surface by
expressing the boundary curves of the trimmed surface as curves in surface
parameter space. These curves, referred to as SP-curves, represent a 3-space
curve with B-spline surface parameter space curves (i.e. B-spline curves with
(u,v) vertices). In cases where the bounded region is the whole of the surface
the trimmed surface can optionally be represented as a surface with no
trimming curves.

Wire edges and biwire edges are not considered, to form part of the
boundary of a face and so will not be represented amongst the SP-curves
returned.

The surface that is trimmed is returned in surf.

The sense argument indicates whether surfs normal points in the same
direction (PK_LOGICAL_true) or opposite to (PK_LOGICAL_false) the face
normal.
If this returned information is to be passed into PK_SURF_make_sheet_trimmed
then the surface and trim data are passed directly to that and then, if the
sense was PK_LOGICAL_false, PK_BODY_reverse_orientation is applied to the
result.

A description of a single trimmed surface is comprised of the
surface to be trimmed, the sense of the surface, trimming information held
in a PK_SURF_trim_data_t structure and three additional arrays.

trim_data returns the trimming information.  The spcurves field of
trim_data is described here.  For further information on trim_data see
documentation for PK_SURF_trim_data_t.

spcurves consists of an array of SP-curves which describe the boundary
           loops of the trimmed surface (these will not necessarily be in
           1-1 correspondence with the loops on the face). Where it is
           appropriate to do so the code will place the outer boundary
           loop of the trimmed surface at the head of the list of loops.
           An example of where this is not appropriate is a trimmed
           surface on a sphere, in this case it is sometimes hard
           to distinguish between outer boundaries and holes.

           Each component trimmed SP-curve of a trimming loop will
           be G1 in in 3-space. This means, however, that it will not
           necessarily be possible to represent a single G1 edge curve
           as a single G1 SP-curve when the surface does not have a
           parameterisation with continuous first derivatives.

           Where an SP-curve is to represent a 3-space curve
           identified as a line of constant surface parameter the
           SP-curve description of it will be in the form of a
           linear B-spline.

Note: if n_spcurves>0 then `trim_set[n_spcurves-1]' says how many trim sets
there are.

The arrays geoms, intervals and topols provide additional information,
if requested, in the options structure.  Information in these arrays at a
particular array index goes with the SP-curve in the spcurves array in
trim_data at the same index. When geoms contains a curve, the
corresponding element in intervals will contain the parametric range
of that curve.

Setting the want_geoms flag in the options structure to PK_LOGICAL_true
causes both the geoms and intervals arrays to be output.


geoms
   'geoms':      An optional array of corresponding 3-space geometry. Each
                 3-space geometry will be either a curve or a point. Points
                 will arise in cases where a SP-curve has been produced to
                 cross a degeneracy in the surface parameterisation.

intervals
   'intervals':  An optional array of geometry intervals where the
                 corresponding geometry is a curve.


topols
   'topols':     An optional array of corresponding model topology. Each
                 topology may be one of fin, vertex or null. Vertices will be
                 associated with parameterisation degeneracies. The topology
                 will be null if the SP-curve represents part of a seam line
                 on the surface underlying the face.


If the trimmed surface has no trimming loops these arrays will be
returned as NULLs.


Deleting Returned Geometry

In the returned data from PK_FACE_output_surf_trimmed all geometries are either
copies of geometry on the face or have been built specifically as
alternative representations of that geometry. To avoid the modeller
filling up with unrequired nodes, the returned geometry arrays
should be deleted as soon as their usefulness expires.