Open API interface to boundary representation routines. This allows you
to extract and create NX solid and sheet bodies.
The UF_BREP module is the basis for NX application code requiring a high level
interface to create and inquire about topology and geometry for solid bodies
and trimmed surfaces.
For a non-trivial working Open API program that uses the UF_BREP module
see ufx_brep.c
The two main uses of UF_BREP are:
1. Asking about BREP topology and geometry via:
UF_BREP_ask_topology:
Returns a Parasolid-like topology tree for an NX solid. Face,
edge, and vertex topology entities contain the NX entity tags
for surfaces, curves, and points, respectively.
UF_BREP_ask_geometry:
Returns raw geometry data for a topology entity, which may not
have an NX entity tag, e.g., a fin and the corresponding SP
curve.
2. Creating BREP topologies via:
Topology structures:
You malloc UF_BREP_topology_s C struct's that form the basis
of the topology tree. You build the topology `scaffolding' by
assigning pointers from parents to children topologies.
UF_BREP_attach_geometry:
Creates underlying NX geometry entities from raw geometry data
that you supply, and logically attaches the geometry to a
topology entity. E.g., attaching a .5 meter radius
cylindrical surface to a face.
UF_BREP_make_body:
Creates an NX body from your topology tree and the corresponding
geometry that UF_BREP_attach_geometry creates.
UF_BREP can also create and ask about trimmed surfaces. The create
and ask methods for these sheet bodies are similar to those for solid
bodies.
Tetrahedron Example
You can use these routines for applications requiring low level control over
non-trivial solid body creation and extraction, e.g., translator applications.
Or for applications that previously created NX solids by creating sheet bodies
and then sewed the sheets together.
For geometry creation the Open UF_BREP API lets you create a topological
model of an NX solid or sheet body. You complete the boundary representation by
attaching geometry to the topological model, e.g., surfaces to faces, curves
to edges.
For extraction, the UF_BREP module returns a topological model, whose individual
entities, e.g., a face or an edge, can be queried for raw geometry and status
data.
Protocols and Tips
Protocols specify UF_BREP functionality and when to use it. A protocol summary
follows.
Since deciding which protocol to use requires some understanding of NX details,
those concepts are defined here. NX has the notion of Topology that can be
considered more or less separately from geometry. The former is the idea of
connecting things together without (necessarily) knowing where they are in
space. The latter is the idea of something specific that can exist in space. A
real object is formed by matching topology with geometry.
Faces (topology) are formed when given a set of loops (topology), each of which
has a list of edges (topology), each of which in turn has one or two vertices
(topology). A surface (geometry) is bounded by curves (geometry) which are in
turn bounded by points (geometry). The connections are defined by the topology.
The topology is given a 3D-space existence by attaching geometry to each of the
relevant topology elements.
A shell is a set of connected faces, e.g., the shell of a solid cube is the six
planar faces. And if the cube also has an internal void, another shell would
define the set of faces bounding the void.
A fin is the topology that connects a face to an edge. Thus where two faces
join there are two fins, one for the loop on each of the respective faces, that
"point to" the edge. Either the fins of the faces connecting to an edge may
have curves, or the edge may have a curve, but not both, in an NX body.
The former situation exists when an edge is made tolerant. In this case, there
is a curve on the fin that is defined as a spline in the parameter space of
the surface, which are the u and v values. These Surface Parameter curves are
called SP curves.
A periodic surface is one that closes on itself. Cylinders, cones, spheres,
and torii are periodic; a (non-degenerate) torus is bi-periodic. B-surfaces may
also be periodic or even bi-periodic. The latter must be smooth at the
closure(s).
A degeneracy is a place on a surface or curve where evaluating it at several
neighboring parameter values results in the same point. The derivatives cannot
be computed at such a point.
A singularity is a place on a surface where evaluating at a range of parameters
does not change the result, where this property is integral to the surface. It
is close kin to a degeneracy; one might say that a singularity is a legal
degeneracy. The tip of a cone is a singularity. It has no extent in 3D space,
but when a cone is represented in its U/V parameter space, it is rectangular;
in fact all NX surfaces have a rectangular parameter space. One entire side of
this parameter space corresponds to the tip of the cone. A bsurface may have a
singularity, as long as it is along one edge or at two opposing edges of the
parameter space.
Regardless of whether an edge is tolerant or not, SP curves for the fins
attached to an edge may be obtained, or a 3D curve for the edge may be obtained,
or both. If the requested data does not exist it is computed, by approximation
if necessary. It is the manner of checking the approximated curves and how well
they must correspond to the solid or sheet body that determines which protocol
to use. This checking primarily has to do with periodic surfaces.
We first concern ourselves with the means of extracting data from an existing
solid or sheet. There are several things to consider:
1. Is a complete boundary representation of the body needed, or does each face
stand alone? In other words, does the correspondence from the edge of one
face to the edge of its adjacent face need to be known?
2. In the treatment of periodic surfaces: must the SP curves be checked to
make sure they represent a loop with constraints, e.g., the loop is closed
and contained within a single period? Or may the SP curves be more loosely
created while ensuring that when interpreted on periodic surfaces, they
define the desired trimming?
3. In the treatment of periodic surfaces and/or singularities are SP curves
needed with a known correspondence to the edge curves of the body? Or may
SP curves be defined as is convenient for NX, which might create more than
one SP curve for a 3D curve?
4. Do surfaces with singularities (spheres, cones) need SP curves to represent
the edges of the parameter space corresponding to the singularity?
5. In the treatment of periodic surfaces: are SP (and/or 3D) curves needed for
the "seam", the line where the surface closes on itself? In particular, is
it necessary that holes in the surface that straddle the seam be split and
merged to make a single outer boundary?
The answers to these questions determine what sort of sequence is used to obtain
the data for a solid or sheet body, and what options are used.
If the body is not needed as a cohesive whole, but instead all faces stand
alone, periodics and singularities don't have much effect on the application's
processing. The recommended protocol is as follows:
1. Obtain a list of the faces of the body and start with the first one.
2. Call UF_BREP_ask_topology on the face. Specify any SP curve modification
options needed. The returned topology represents only the desired face.
3. Call UF_BREP_ask_geometry as needed to get all the geometry.
4. Call UF_BREP_release_topology on the topology returned in step 2.
5. Get the next face and go to step 2.
If the face must be represented with a closed outer boundary contained within a
single period of the surface, specify the flattening with periphery option. If
it is permissible to represent the face without an outer boundary (if it is not
needed), and if it is permissible to represent the trimming without a closed SP
curve loop (the 3D loops will still be closed), specify the flattening option.
If no option is specified, fewer checks are made on the SP curves and it is
possible that some curves may be shifted by a period on periodic surfaces. This
does not harm the interpretation of the data in NX, but other systems
(such as may be used via a translator) may not be able to accommodate such data.
If the result contains more than one face, then it was necessary to divide the
face to obtain a representation meeting all the constraints on the SP curves.
You can either process them as several separate faces, or combine the curves to
represent one face in which the curves either extend outside one period.
If the body is needed as a cohesive whole, and either SP curves are not needed
or they may be output as is convenient for NX, use the following protocol:
1. Call UF_BREP_ask_topology on the body (without any SP curve modifications).
2. Repeatedly call UF_BREP_ask_geometry to obtain the surfaces, curves, and
vertices.
3. Call UF_BREP_release_topology on the topology returned in step 1.
If the body is needed as a cohensive whole (B-REP), but periodic faces must be
flattened with a periphery, you need to do extra work. Flattening is also
called seam-realizing; the curves are divided in the output, and where the face
closes are used to split any loops that straddle the seam. The result
incorporates the loops defining the ends of the face, the curves of the seam,
and any holes straddling the seam, into one peripheral loop. Use the protocol:
1. Call UF_BREP_ask_topology on the whole body. Flattening cannot be specified
for this call.
2. For each face, call UF_BREP_ask_topology. Specify the flattening options
needed. The results contain the seam curves and the split holes, and
combine several loops into the single peripheral loop. To produce your
output, you need to search the children list and match up the identifiers.
Secondly, we concern ourselves with creating a body. Consider the following
questions:
Is the body to be built from a complete boundary representation, or is it a
sheet to be built by trimming with curves?
Are vertices available?
If vertices are not available, and you do not want to compute them, then you
have to build a sheet with trimming curves. Other qualities necessary to build
a body as described above that may not be present in the data include
direction/sense data for the surfaces and edge curves. Lack of these data
also indicate that the sheet should be built with trimming curves even if
vertices are present.
To build a body from a complete boundary representation, use the following
protocol:
1. Build the topology structure and optionally call UF_BREP_validate_topology
to catch non-geometric problems.
2. Repeatedly call UF_BREP_attach_geometry to create the geometry of the model.
To replace geometry you have already created, use UF_BREP_delete_geometry
and then call UF_BREP_attach_geometry again.
3. You may extend the topology to add items, as determined from geometry
states and any other examination you might do. Allocate, initialize, and
link together any new topology structure elements. For debugging use
UF_BREP_validate_topology to catch topology errors.
4. Call UF_BREP_make_body to complete the process.
To build a sheet body from bounding curves, use the following protocol:
1. Build the topology structure, set the body type to abbreviated (or begin
with the face), and optionally call UF_BREP_validate_topology. You need not
include vertices (they are ignored if present) and you need include only
the type of curves that are used for trimming (SP curves or 3D curves); the
others are ignored. The body and shell topology items may also be omitted.
2. Repeatedly call UF_BREP_attach_geometry to create the geometry of the model.
3. You may extend the topology to add items, as determined from geometry
states and any other examination you do. Allocate, initialize, and link
together any new topology structure elements. For debugging use
UF_BREP_validate_topology to catch topology errors.
4. Call UF_BREP_make_body to complete the process.
Normally, the values of the edge senses and attached curve orientations are
not necessary to create the desired trimmed surface. However, for a closed
surface and one trim loop (i.e., no holes), UF_BREP does require the sense
and orientation information. For example, if a spherical surface has an
equatorial trim curve, then is the desired face the southern or northern
hemisphere?
To decide in such cases, UF_BREP uses the `left hand' rule. In the
hemisphere example, if the edge sense and edge curve orientation are
FORWARD and the equator curve parameterization increases in the westerly
direction, then the resulting face is the southern hemisphere.
5. Call UF_BREP_release_topology.
At times, it may be necessary to abort creation of a body. Use
UF_BREP_release_topology to do this, any time before UF_BREP_make_body is
called. After using UF_BREP_make_body, use UF_OBJ_delete_object with the body
tag. Don't use UF_BREP_release_topology.
It may be desired to create geometry for the purpose of evaluating and examining
it, without creating a body. Do this as follows:
1. Create and initialize a topology, e.g., with the UF_BREP_INITIALIZE_TOPOLOGY
macro. Set the type fields to the appropriate types for the geometry you
wish to attach.
2. You may then attach geometry to the topology entities and evalulate it with
UF_BREP_ask_geometry.
3. Use UF_BREP_delete_geometry to delete the geometry.
Memory Handling
All memory returned by UF_BREP_ask_topology must be freed with
UF_BREP_release_topology. If you are creating your own topology, e.g., via
UF_BREP_make_body, you must free memory you allocate (including the oriented
children arrays), or you must supply UF_BREP_release_topology or
UF_BREP_free_geometry_data with a free function that can free the memory you
have allocated.
UF_BREP_ask_geometry allocates memory for various items. You can free the
memory with UF_free, or you can call UF_BREP_free_geometry_data with a NULL
free function argument.
For example, some geometry types contain data in arrays pointed to by members
of their structure. The geometry structure itself is provided by the caller
(and therefore must not be freed with UF_free), but the arrays (like knots for
a spline) must be freed by UF_free when returned by the above functions.
Extruded and revolved surfaces have extra structures to represent the generators
that must be freed by UF_free.