PK_SURF_make_sheet_trimmed

PK_ERROR_code_t                       PK_SURF_make_sheet_trimmed
(
--- received arguments ---
PK_SURF_t                             surf,         --- surface
PK_SURF_trim_data_t                   trim_data,    --- trim data
double                                precision,    --- precision for each edge
const PK_SURF_make_sheet_trimmed_o_t *options,      --- options structure

--- returned arguments ---
PK_BODY_t                      *const body,         --- sheet body
PK_check_state_t               *const state         --- state of body
)


Creates a sheet body given surface and trimmed curve data.

This function does not support facet geometry [NF]


Specific Errors:
    PK_ERROR_bad_tolerance           given edge precision too small
    PK_ERROR_has_parent              surface or sp-curves are not orphans
    PK_ERROR_unsuitable_entity       surface must be G1 and it must be
                                     periodic if closed
    PK_ERROR_not_on_surface          curve does not lie on surface
    PK_ERROR_bad_sharing             curve is from another surface
    PK_ERROR_bad_shared_dep          dependent of entity would be illegally
                                     shared
    PK_ERROR_failed_to_create_sp     SP-curve generator failed for unknown
                                     reason



This function creates a sheet body with a single face, given surface
geometry for the face and curve geometry for the edges.
The topology of the resulting sheet will be inferred from the geometry.

PK_SURF_make_sheet_trimmed is designed primarily for importing
geometric data of lower precision than Parasolid default.
The geometry supplied to the routine need not, therefore, conform to
Parasolid's standard precision. The user is responsible
for specifying the precision, the minimum distance two
points have to be apart to be regarded as distinct, which will be stored
with the edges of the resulting sheet body.


Received arguments:


'surf' will be the geometry attached to the single face of the body.  It
can be of any type recognised by Parasolid, and must be orphan. If
'surf' is a B-surface, it must be capable of passing the continuity
checks imposed by PK_GEOM_check.



'trim_data' provides the trimming information.  The 'spcurves' in 'trim_data'
are described here.  For other information on 'trim_data' see documentation for
PK_SURF_trim_data_t.

'spcurves' consists of an array of curves which describe the boundary
           loops of the trimmed surface. 'spcurves' is not
           allowed to be null, except in the case of a wholly
           closed sheet with no loops e.g. whole sphere or torus.
           Each curve in 'spcurves' may either itself be an SP-curve or it
           may be any 3-space curve which will be used to generate an
           SP-curve.

           Note that PK_SURF_make_sheet_trimmed will not incorporate
           curves representing surface degeneracies
           into the model, as these have zero 3-space length.
           Similarly bounded curves shorter than the requisite tolerance
           (in terms of chord length) will not appear in the model
           (closed SP-curve are excepted).

           Note that two coincident opposing curves must be supplied
           if a wire edge (corresponding, for example, to a seam on a periodic
           surface) is required. In addition, PK_SURF_make_sheet_trimmed
           will always create closed loop topology, regardless of
           the actual geometric closure of the supplied loops of curves.

           If the supplied bounded curves are SP-curves, they must satisfy the
           continuity requirements described under PK_SPCURVE_create before
           introduction into a model by means of PK_SURF_make_sheet_trimmed.

           If SP-curves are not available, application can supply 3-space
           curves in the 'spcurves' array, which constitute the boundary loops
           of the trimmed surface.
           These 3-space curves must either be coincident with the surface
           or supplied interval of the curve must lie within the
           supplied precision of the surface. If curve is not coincident
           with the surface and lies within the supplied precision of the
           surface, an SP-curve is computed internally and the supplied
           3-space curve will be attached as nominal geometry to the
           edge if nominal geometry is enabled.
           If an SP-curve is computed internally then Parasolid may extend
           the supplied 'surf' so that the surface of the resulting sheet
           body includes the entire length of the SP-curve.

           The points stored on the vertices of the sheet body will be
           computed by Parasolid, so the application has no need to
           supply them. The position of the vertex is deemed to be the
           centroid point of all the trimmed curve ends meeting at the vertex.
           A suitable precision for the vertex is also computed.
           It should be noted that because the vertex point and
           precision are flexible to some extent, it is not necessary that
           consecutive spcurves meet to within twice 'precision' at the vertex.
           As a safeguard against potentially incorrectly ordered data,
           however, there will be a state code indicator returned when
           any computed vertex tolerance exceeds 10 times 'precision'.

The 'trim_set' field in 'trim_data' is ignored.  The function may only be
passed a single trim_set.

If the resulting sheet body has its face normal in the wrong direction,
then this can be swapped with PK_BODY_reverse_orientation



'precision' is a 3-space distance parameter, and will be stored with all of the
edges of the resultant sheet. Refer to PK_EDGE_set_precision for the meaning
of this tolerance within a model. From an application point of view,
the value of 'precision' will reflect the accuracy of the sending system's
curve data, and must be greater than or equal to Parasolid's linear tolerance.
PK_EDGE_set_precision can be used subsequently to modify the tolerance
of any edge of the resultant sheet.


checking option structure:

There are three optional levels of checking available on the resulting
sheet body. These can be employed by the application according to how much
is known about the input data in terms of, for example, the consistency of
the loops directions. Whichever option(s) used, PK_SURF_make_sheet_trimmed
will attempt to correct any inconsistencies found within the limits
imposed by the checks.
Note that each option is independent of the others.



'check_wires'    : This option allows the identification of wire topologies
                   (e.g. seamlines) and will ensure that the
                   correct topology is made in such cases.



'check_self_int' : This option enables the application to detect
                   topological self-intersections. Checks made are:

 . All edges are tested pairwise with each other to detect points at which
   their fin curves intersect which are NOT model vertices. There is no
   possible corrective action that can be taken here. Such sheets will fail
   PK_BODY_check.



'check_loops'    : This will check that the loops of the face are consistent.
                   With this option set to PK_LOGICAL_true checks are made to
                   check whether:
                       . The loops are correctly contained
                         (i.e. all inner hole loops lie within
                         the boundary or peripheral loop,
                         where such can be determined).
                       . The combination of loops is a valid
                         one for the surface type (for
                         example, a set of loops on a plane
                         contains just one peripheral positive
                         loop and the rest negative hole ones).

 . If the above conditions are not met minimal corrective action is attempted.
   In an attempt to create valid loops PK_SURF_make_sheet_trimmed
   may reverse loops, and investigate singularities of 'surf' introducing
   them into the face as isolated vertices if necessary. This corrective
   action is only attempted if 'check_loops' is set to PK_LOGICAL_true,
   and there no guarantee of valid result being found.


'nominal_geom'    : This option enables the supplied 3-space curve to be
                    attached as nominal geometry on the edge


Returned arguments:



The resulting sheet is returned in 'body'.



'state' is an indicator of the validity of the sheet after the chosen
checking options have been performed on it. It is not intended to give
detailed information (use PK_BODY_check for this). The returns are:



PK_BODY_state_ok_c:  Indicates that either all selected checks passed,
and any attempted corrections were successful, or no checks were requested.



PK_FACE_state_redundant_c : Face is redundant with respect to the
supplied tolerances. This is because all the supplied curves were too short
with respect to 'precision' for the production of a valid face.



PK_CURVE_state_inconsistent_c : Indicates that no sense could be made
of the input loops of curves. This means that they did not follow
round in the loop direction as indicated earlier, and there may be vertex
tolerances computed as a result which exceed 10 times 'precision'.



PK_FACE_state_self_int_c : Indicates that the resultant sheet is
self-intersecting because edges meet at a place other than a model vertex.



PK_LOOP_state_invalid_c : Indicates that the loop structure of the
resulting sheet is in some way invalid (e.g. there is no peripheral
loop on a planar surface), and attempts to correct the problem failed.
Such sheets should NOT be subsequently incorporated into solid bodies.



PK_EDGE_state_bad_order_c : Indicates that the edges of the resulting sheet
are incorrectly ordered at at least one of its vertices. This can be caused
by the input data failing to comply with the convention on wire edges,
for example.