All Frameworks  Class Hierarchy  This Framework  Indexes

SPAds Global Function DM_make_bspline_surface

Creates a B-spline surface from data and returns a pointer to DS_pfunc B-spline surf or NULL.

Role: Modifies return_err.

Creates and returns a pointer to DS_pfunc B-spline surface representation. A B-spline surface is the tensor product of the underlying B-spline u-curve and v-curve basis functions. The total number of dofs in the surface is just the product of the dof counts for u and v curve basis functions. The global dof numbers for each dof are the cross product of the u-curve and v-curve dof numbers with the v-curve dof numbers varying the fastest. This function's input arguments contain enough information to make both the u-curve and the v-curve basis functions as well as the dof values for the surface.

image_dim is the size of the model space, using 2 for 2D and 3 for 3D. degree_u and degree_v are the B-spline polynomial degrees in the surface's u and v directions. dof_count_u and dof_count_v are the number of B-spline control points in the surface's u and v directions. dof_count_u and dof_count_v are the number of B-spline control points in the surface's u and v directions. The knot_count_u and knot_count_v are the number of unique knot values in the surface's u and v directions.

The total_knot_count equals the dof_count + degree - 1 for each u and v surface direction. The total_knot_count will not equal the distinct knot_count when the NURB has any multiple knots. The multiplicity of each knot is communicated through the knot_index array. Each knot, starting with the lowest u value knot, is assigned a knot_index starting at 0. The knot_index array records the highest index value for all knots at each distinct knot location. For example, a common B-spline is one with multiple knots on the end points and single knots in the interior. A map of the knot index values might look like:

 +------+------+-------+------+
 0  3  4  5  6
 1           7
 2           8 

This knot array corresponds to a degree = 3 B-spline with seven control points and four spans. The B-spline interpolates the first and last control point positions due to the multiple end knots.

There are nine total knot values and only five distinct knot values. The knot index array for this curve would be [2,3,4,5,8]. The knot array contains the domain space values (u values) for each distinct knot. For the above example, the knot array might be something like [0.00, 0.25, 0.50, 0.75, 1.00] for an even distribution of knot values from 0 to 1.

Other common B-spline representation schemes store an extra unused knot at each end of the knot array. These extra knot values seem to appear in all the B-spline evaluation functions but in reality are never used and are not input to the deformable modeling package. Developers moving B-spline data between this and other systems must take care to watch out for this mismatch possibility on the end knots.

The dof_vec contains the surface's control point locations and is sized [image_dim*dof_count_u*dof_count_v]. It is ordered by control point, so a two dimensional surface with a 2x2 grid of control points will be organized as:

 dof01  dof11  Global dof numbers
 +----------+   dof0 = dof00
 |   |   dof1 = dof01
 |   |   dof2 = dof10
 |   |   dof3 = dof11
 +----------+
 dof00 dof10
 

and will have a dof_vec stored as [x0, y0, x1, y1, x2, y2, x3, y3], and the same surface in 3d would be stored as, [x0, y0, z0, x1, y1, z1, x2, y2, z2, x3, y3, z3]. Deformable surfaces have both a current shape and a default shape. The default shape is stored as a second array of control points called dof_def. dof_def is sized and stored in the same manner as dof_vec.

Surfaces can have three different end conditions applied to them through the use of constraints. These include an end_cond which can force opposite edges of the surface square to connect to each other with either a C0 or a C1 continuity, and a singularity case which can collapse an entire boundary edge into a single point. These end conditions are communicated through the use of four flags, end_cond_u, end_cond_v, singular_u, and singular_v. The connectivity of the u and v boundary curves are set independently by the end_cond_u and end_cond_v flag values. When end condition equals 0 the surface remains open in that direction. When end condition equals 1 it will be C0 across the end curves. And when end condition equals 2 it will be C1 across the end curves. The singularity of the u and v boundaries are set independently by the singular_u and singular_v flag values. When singular equals 0 all edges are normal. When singular equals 1 the low end boundary curve is collapsed to a point. When singular equals 2 the high end boundary curve is collapsed to a point. When singular equals 3 both low and high end boundary curves are collapsed to a single point.

Returns a pointer to DS_pfunc when successful or NULL when a problem is encountered in the input.

mallocs: The calling program needs to call DM_delete_pfunc on the returned pointer. The new data structure does not reference the input arrays after this call.
Errors:

DM_BAD_IMAGE_DIM_VALUE

The input value of the image dimension must be positive.

DM_BAD_DEGREE_VALUE

The requested spline degrees must be 0 or greater.

DM_BAD_KNOT_COUNT_VALUE

The number of knots must be positive.

DM_NULL_INPUT_PTR

The knot_index and the knot_array pointers cannot be NULL on input.

DM_BAD_KNOT_TO_CPT_COUNT

The last knot index number must equal dof_count + degree - 2.

DM_BAD_END_COND_VALUE

The end condition values must be 0, 1, or 2.

DM_BAD_SINGULAR_VALUE

The singular values must be 0, 1, 2, or 3.

DM_BAD_NTGRL_DEGREE_VALUE

The required gauss integration degree is not supported. Currently limited to the range 1 to 79. The ntgrl_degree must be equal to or larger than twice the spline degree for valid deformations.

Effect: Changes model

Parameters:

rtn_err

out: 0=success or negative err code.

image_dim

in: image space size (2=2d,3=3d).

degree_u

in: u dir polynomial degree.

dof_count_u

in: u dir control point count.

knot_count_u

in: u dir distinct knot value count.

knot_index_u

in: u dir multiple knot count array. sized:[knot_count] specify the multiple knots by setting count[i] = maximum knot index value for location knot[i] Examples: no multiples count = [0,1,2,3,4] some multiples = [1,2,4].

knot_u

in: u dir knot values sized:[knot_count] ordered [u0 < u1 < u2...].

degree_v

in: v dir polynomial degree.

dof_count_v

in: v dir control point count.

knot_count_v

in: v dir distinct knot value count.

knot_index_v

in: v dir multiple knot count array. sized:[knot_count] specify the multiple knots by setting count[i] = maximum knot index value for location knot[i] Examples: no multiples count = [0,1,2,3,4] some multiples = [1,2,4].

knot_v

in: v dir knot value array sized:[knot_count] ordered [u0 < u1 < u2...].

dof_vec

in: init dof_vec vals or NULL for 0 sized:[image_dim* dof_count_u* dof_count_v] ordered:[C00, C01, ... C0m, C10, ... Cnm].

dof_def

in: init default shape or NULL for 0 ordered:[C00, C01, ... C0m, C10, ... Cnm].

end_cond_u

in: one of 0=open or 1=closed or 2=periodic.

singular_u

in: one of 0=none or 1=low or 2=high or 3=both.

end_cond_v

in: one of 0=open or 1=closed or 2=periodic.

singular_v

in: one of 0=none or 1=low or 2=high or 3=both.

sdmo

in:SDM_options pointer note: total_knot_count = dof_count+degree-1 the total and distinct knot counts vary when there are multiple knots note: the input array values are only copied. The calling program still needs to manage that memory.

Copyright (c) 1989-2007 by Spatial Corp. All rights reserved.