Curves, surfaces, and volumes are represented by
the class VsMapNd as
VsMapNd<1>, VsMapNd<2>, and VsMapNd<3>
respectively. A VsMapNd
object can be translated from a pointer to a known format (currently
just NLib's Nurb format)
or created from a list of knot, weight, and control point values.
VSLib builds a minimization problem given a starter
shape. The minimization
problem is encapsulated in the class VsQMinNd. The class is called "QMin"
rather than just "Min" because VSLib limits itself at this time to
quadratic minimization problems, an interesting subset of all possible
All subsequent interactions for specifying the nature of the
optimization problem, solving it, and getting its solution back out of
the library are done through this top level object.
A minimization problem consists of a shape and a
list of terms. Understanding and using the minimization terms
effectively is the heart of exploiting VSLib for shape design. Each term specifies either a
constraint or a desired property to be optimized during the solution
phase. The key idea for programmers and end-users to understand is
that every unique combination of terms yields a different final shape,
so desired shapes are designed by selecting desired combinations of
Minimization terms can be added or removed from
their minimization problem independently.
Minimization terms all have parameters that can be
modified at run time, each new combination of parameter values yields
a new optimized shape.
Minimization term implementations are all derived
from the class VsQTermNd. A VsQMinNd minimization problem
contains a list of VsQTermNd objects.
Any minimization problem can have a default
shape. That is the shape
which is found by the solution when no other minimization terms are
applied. Think of a plastic ruler. In its rest configuration its
flat and about a foot long.
This is its default shape. But once some bending loads
are applied to its ends the ruler bends into an arc. This is its deformed
shape. In VSLib the
bending loads are added to the minimization problem by adding load
terms as described later.
The deformed shape is found by solving the minimization problem
once the bending loads have been specified.
Minimization problems that have no default shape
act as if they have a zero default shape, that is, solutions collapse
all the image points of the shape into one single no-length, no-area,
no-volume, point location.
Unlike all other terms, the default shape is not
derived from the VsQTermNd class. Instead it is stored as a list
of default shape parameter values within the VsQMinNd class.
VSLib shapes are made smooth and fair by adding
smoothing terms to the minimization problem. There are 4 kinds of smoothing
terms and each is controlled by a single gain parameter as described
The smoothing effects are bundled together into a
single minimization class called VsStiffNd because the
smoothing terms all act together to define the "stiffness" behavior of
the object being sculpted.
These were bundled together for convenience since most
applications will want to work with ratios of the four behaviors. To turn off any one behavior
set that behavior's gain value to zero.
Currently smoothing terms are applied to the entire
shape, but in future releases smoothing terms will be able to be
specified sub-domains so that several smoothing terms can be used
together to specify smoothing behaviors that vary over the extent of
the shape. Until that
change is made there is no advantage in having more than one smoothing
term per minimization problem.
Multiple terms simply add together and take a little longer to
run than just one smoothing term.
Alpha is the name of the gain applied to a
resistance to stretch term.
Shapes that resist stretch act like soap bubbles or sheets of
rubber. Wherever they
can, they shrink to find the minimum area shape that still satisfies
all the other constraints that are applied to the problem. Like soap
bubbles these shapes tend to be very graceful and have a very organic
feel to them. Without any
constraints or a default shape, a shape that minimizes its stretch
will shrink to a no-area, no-volume single point solution.
Beta is the name of the gain applied to a
resistance to bending term.
Shapes that resist bending act like thin metal sheets spreading
out sharp bends over large areas to make nicely rounded smooth
shapes. Shapes that
minimize bending will be curvature continuous often a feature
considered required for designing fair shapes. Without any constraints or a
default shape, a shape that minimizes its bending will flatten out
into a linear or planar shape.
Often times the alpha and beta terms conflict with
one another. A large beta
tends to increase the area of an object to avoid small areas of very
high bending while a large alpha tends to isolate all bending into
small corners in the pursuit of minimizing the area of the
interesting families of smooth and graceful shapes can be generated by
varying the ratio of alpha to beta at run time. For numerical reasons
significant changes in shape only happen for large changes in alpha
and beta values. When
varying a beta value, try varying it by orders of 10, i.e. try 1, 10,
100, 1000, 1e4, 1e5, 1e6, 1e7, and 1.e8.
(Feature implemented - not yet tested) Gamma is the
name of the gain applied to a resistance to the rate of change in
bending term. Shapes that
minimize this term will tend towards C3 continuous meaning
that the beta term's tendency to smooth out areas of curvature will be
complimented by a tendency to seek out large areas of constant
curvature. Solutions will
tend towards circular and spherical shapes.
(Feature implemented - not yet tested) Delta is the
name of the gain applied to a resistance to displacement term. This terms acts like a
distributed spring connecting every point in the default shape to its
partner point in the deformed shape. Larger values of delta will
force the solution shape to stay nearer the default shape. This behavior can be used to
isolate the range of effect that another constraint or load has over
the whole shape. For
example, a shape with a large delta value subject to a point
constraint will deform locally to meet that point constraint. Without the delta term, the
deformation to meet that point constraint will be made globally.
Point Constraints (interpolation)
Point constraints are implemented in the class VsPointTermNd.
Point Constraints will be the primary mechanism
used by end-users to sculpt shapes at run-time.
One point constraint specifies the image location
of one point on the shape identified by its domain location. Every solution of the
minimization problem will always produce a shape that exactly
interpolates all its point constraints.
A minimization problem can have any number of point
constraints and can constrain any combination of locations within the
shape. The only limit on
the number of point constraints is that one can not constrain more
points in a shape element than there are degrees of freedom in that
element. This means that
you can't have more constraints than control points. If you want more constraints,
just insert knots into your BSpline shape until you have enough
Most importantly, a point constraint is not limited
to specifying the image space location for a shape point; it can also
specify any combination of that point's differential properties. For curves, this means that at
any point on the curve and for any number of points on the curve, the
position, tangent, normal, binormal, and curvature properties can be
set as constraints. For
surfaces, positions, tangents in two independent directions, surface
normals, and curvatures in two independent directions can be
specified. For volumes,
positions, tangents in three independent directions, and curvatures in
about those tangents can all be specified.
Very complicated, interesting, and well behaved
shapes can be designed by sculpting the properties of a few "critical"
points rather than working with a larger number of simpler
point-position constraints, or even worse, working directly with the
even larger number of shape parameters.
Curve Constraints (interpolation)
(not yet implemented)
Curve constraints are trans-finite point
constraints. A solution shape will exactly interpolate the curve's
position at every point along the curve's shape. Curve constraints are useful
for matching up one surface to another in Boundary Representation and
Quilt style models.
A curve constraint is defined by a curve in the
domain space and acts to constrain the solution shape's image space
position along the points of that curve.
A minimization problem can have any number of curve
constraints and each curve constraint can have any domain space
And like point constraints, not only the image
space positions but also all the differential geometry properties at
the points along the length of the curve can be constrained. This feature is helpful for
connecting neighboring surfaces with G0, G1, and
Point Loads (approximation)
Point Loads are also implemented in the class VsPointTermNd. The difference between the
point load and the point constraint implementation is a state bit
which is set when the VsPointTermNd object is
Point Loads exhibit all the same behaviors as point
constraints with one very important difference. A shape solution will exactly
interpolate a point constraint, and will only approximate a point
load. This is a nice
property for approximating applications where a very large number of
sample points are to be approximated by a shape with just a few shape
Point loads act like springs connecting an image
space property, like position to a desired target value. Point loads have a gain that
acts like the spring's stiffness. Larger gains force the
solution shape to more closely approximate the specified values. The solution does not find
approximations limited to a tolerance value.
This behavior can be achieved by writing an
iterative algorithm that approximates the points with a low
degree-of-freedom count shape and if the tolerances are too high can
either increase the load gain values or use knot insertion to increase
the number of degrees-of-freedom in the shape. As the number of
degrees-of-freedom increases to the number of sample points the
solution will tend towards an interpolation. The iterative algorithm can be
made to stop once a desired tolerance is achieved. Different strategies for
selecting where and when to insert new knots will impact the number of
control-points needed to get the approximation to within
Curve Loads (approximation)
(Not yet Implemented)
Curve loads have the same features as curve
constraints but come with an extra gain factor that controls how
closely the solution shape approximates the curve load parameters.
Body Loads (sculpting)
(not yet implemented)
Body loads are minimization terms that sculpt the
entire shape with a single affect. Body terms are useful
sculpting tools because they can be made to mimic how the real world
acts to shape physical shapes and as such are inherently intuitive to
Gravity: Gravity is a body
term specified by a gain and a vector. Its a force that pulls the
solution shape at all points in the same direction. The larger the
gain the more the shape sags under gravity. Gravity's down direction is
specified by its vector.
Pressure: Pressure is a body
term specified by a gain.
Its a force that pushes each point in a solution shape in the
direction of its surface normal.
When built into an iterative loop the pressure force can be
used to design closed surface objects of constrained volume. It's left to the user's
application to build the iteration algorithm.
Attractors (Repulsors) are body terms specified by a gain and a
position. All points in a
solution shape are attracted (or repulsed) along a line from the shape
point to the attractor (repulsor) point. The gain specifies the
magnitude of that attraction (repulsion).
Solving the minimization problem
Solutions to completely specified minimization
problems are found by a call to the VsQMinNd::Solve() method. The solution is a complicated
numerical process that builds up a set of matrix equations, solves
them, and places the solution shape in memory. The final solution results in
a set of modified control point locations for the VsMapNd object stored within
the VsQMinNd minimization
problem object. To see
the solution, fetch the modified shape and use your favorite shape
rendering functions for display.
Designing with minimization problems
Whether at run-time by an end-user or at
programming time by a developer the act of designing shapes with VSLib
is turned into the act of defining the correct minimization problem
and then asking the package to solve the problem to get the final
To keep things manageable, VSLib turns the problem
of defining a minimization problem into an exercising of selecting
which combination of terms is desired. No knowledge of advanced math
is assumed or required.
Once the desired combination of terms is accumulated, the
parameters of those terms can be modified to produce a family of
candidate shapes. The
final shape is found by selecting a final set of term parameters.
Each of the terms that can be included into a
minimization problem is designed to have an intuitive,
simple-to-understand behavior so that VSLib users can predict how the
inclusion of that term will affect the final solution shape. These terms include:
Terms - to give the shape a natural tendency to be smooth and fair
in a variety of controlled manners. Parameters are available to
switch between flatter and more rounded shapes. Terms are also available to
control the amount of shape that will be effected by point
constraints. A gain is
provided which will modify the how hard the solution shape tries to
isolate a point constraint's effect.
Constraint Terms - to force the solution shape to interpolate a set
of point locations.
Interpolation properties include position, tangent, normal,
bi-normal, curvature, and surface normal properties.
Constraint Terms - to force the solution shape to interpolate an
infinite number of points situated along a curve within the shape.
- Point Load
Terms - to make the solution shape approximate a set of point
Approximations properties are the same list of properties as
the interpolation properties.
A gain is provided for each point load to set how hard the
solution shape tries to approximate that particular load.
- Curve Load
Terms - to force the solution shape to approximate an infinite
number of points situated along a curve within the shape.
- Body Load
Terms - General affects to allow the controlled deformation of the
entire body in predictable manners. Body loads include affects
such as gravity, pressure, and attractors.
Shapes - Default shapes allow an application to make small smooth
deformations to an existing shape such as in healing or in
With VSLib, designing a shape or a shape algorithm
becomes an engineering problem in which conflicting desires are often
balanced. For example, add in a constraint to force a point
interpolation, but then add in a smoothing term to keep the final
solution graceful, but then add in a little resistance to displacement
to isolate the area around the interpolated point, and so on. Shape design is moved
from being a search of the shape parameter space to a search of this
new space consisting of minimization terms and their parameters. The advantages of making this
change all add up to easier and better shape design. This advantages include:
- There are
many fewer minimization terms and parameters to vary than
control-points in a free-form shape minimization model.
minimization terms, especially the constraints, capture the design
intent of shape design. So although the users are
working indirectly on the shape representational parameters, they
are typically working directly on shape's desired features.
variation in a minimization term is associated with a new shape in
which all the other constraints and effects are still enforce. When working directly with
shape parameterizations, any shape parameterization variation, like
moving a control-point, may or may not enforce or break a previously
achieved constraint or effect.
In other words its very hard to keep a shape smooth when
moving control point locations directly.
Since every variation to a minimization term
produces a new optimized shape, the best approach for using VSLib for
shape design is to build an interface to the package that allows the
space of terms and their parameters to be quickly explored. To show this possibility, we
have built a simple and quite limited interface, called VSLib Test,
into our ui-test program application as described in the next
The ui-test demo and
debugging application used by SMS to develop NMTLib and
NLib has been
extended with an interactive component to exercise the functions of VSLib. This interface
package is called VSLib Test and consists of two components, a dialog
box and a set of mouse driven pick-and-drag functions executed in
ui-test main graphics window.
VSLib Test Dialog Box
The next image shows the VSLib Test dialog box in
its startup configuration before a shape or its associated QMin model
has been built.
The functions within the "Test Shape" box in the
upper left part of the dialog box are used to create very simple
starter shapes. The Curve, Surface, and Volume radio buttons each
create a BSpline and cause it to be displayed in the main ui-test
graphics window when clicked.
The M, N, O values specify the number of control points that
get used in the constructed shape. The control-point count for curves
is [M], for surfaces is [MxN], and for volumes is [MxNxO]. The "Test Shape" constructor
functions are re-start functions. When these are clicked any
existing shape and its associated minimization problem is deleted and
replaced by a new starter shape with no minimization problem.
The set of "Draw" functions underneath the "Test
Shape" functions are a set of check box options. Clicking any of these options
on or off will cause the ui-test main's graphic window to be
redisplayed using the new draw options. The curvature comb drawing
feature has two settable parameters, the tine count and gain. The tine count controls how
many curvature "tines" are drawn per shape element and the curvature
gain allows the length of each tine to be scaled to better show the
curvature. It turns out
that the curvature comb is easier to perceive when drawn with a
negative drawing gain.
These "Draw" functions can be executed at any time without
changing the starter shape or its associated minimization problem.
Shaping: Volume shapes can be used for 3d Field shaping in which
the volume models space.
Objects within that space are deformed as the volume is
deformed. To see and use
3d Field Shaping do the following.
- Read in your
favorite BRep model.
- Click the
"3d Field Shaping" check box on.
- Create a
starter Volume by clicking the Volume radio button.
- Add a
stiffness term, corner point constraints, and a central point
constraint by clicking the appropriate buttons once as described
later in this document.
- Change the
shape of the volume and watch the contained BRep model deform by
tracking any of the volume's point constraint positions. Read below
to see how to drag a point constraint.
- The I/O
for this sequence is a little naive in its implementation and any
deviation from the above sequence is likely to fail. Sorry for the I/O
solution time is too slow in two parts. The VSLib solver is too
slow and the rendering is too slow. I have plans to rewrite
the solver to speed it up.
I also believe, but don't know, that I can use callbacks
within OpenGL to avoid having to remesh the BRep display each time
the volume shape changes.
I'm not sure about that yet, but will look into it.
inspection, there seems to be something wrong with the solution z
components of the volume displacement. That's a bug that I saw
while writing these release notes and that will be fixed directly.
The center of the dialog box is dedicated to
managing minimization terms.
Clicking the <Add Stiffness Term> button adds a stiffness
term to the minimization problem with default alpha, beta, gamma, and
delta values. The <Add
Corner Constraints> button adds a position-point constraint at each
corner of the starter shape.
There are 2 corners for curves, 4 corners for surfaces, and 8
corners for volumes. The
<Add Point Term> adds a point constraint to the center of the
current shape. Click
these buttons just once per starter shape. Adding multiple constraints
atop one another is a mistake and it's a known problem with this
interface to allow this to happen. Also adding multiple stiffness
terms is equivalent to just increasing the alpha, beta, gamma, and
delta values of a single stiffness term.
Each time a term is added to the minimization
model, a line is added to the list box. The following image shows the
dialog box after creating a curve starter shape and adding to it a
stiffness term, corner constraints, and a center point constraint.
Each time a VSLib Test button is used to create a
new object, the ui-test graphics window is updated to show the
change. The next figure
shows the graphic window for a starter curve shape with 3 point
constraints and a stiffness term. In this image, green is
used to display the shape being modified and red is used to show the
constraint point positions.
There is no associated graphic for the stiffness term.
Another dialog box is used to modify the terms of
any active minimizing term.
A term can be made active by either clicking on its name in the
list box or by dragging the mouse over its graphic in the ui-test
graphics window. The next
image shows the dialog box used to modify the alpha, beta, gamma, and
delta values of a stiffness load. This dialog box is shown
whenever a stiffness term is targeted by clicking its item name in the
The individual values can be changed by typing in
the text boxes. When a point constraint is targeted the following
dialog box is displayed.
The contents of this dialog box vary depending on
the domain dimension of the shape being modified. This box is currently
configured for a curve.
For example, if this point term were being applied to a surface
or a volume, v and w domain point values would be shown. Also domain space vectors
specifying the directions to be used for tangent and curvature
For convenience a point term can be applied to a
set of point locations.
This is helpful for approximation applications where a single
shape may be made to interpolate or approximate a large array of
target points. The "Point
Count" and "Target Point Index" boxes tell how many point locations
are set by this one point term and which particular point term is
being targeted by the interface.
The "Constraint" label reports that this point term is being
used as a constraint. If
this point term were a load point instead of a constraint point, an
extra "gain" value would be displayed to set the load point's spring
The check and value boxes that are labeled with the
word "image" control how the point term constrains the shape. Each marked check box shows
which shape differential properties are being constrained by this
term. The point
constraint's behavior can be changed by clicking these check boxes on
and off. In this image,
only the "Image Point" behavior is turned on. When a behavior is checked on,
the x, y, z values to the right specify the target location in image
space to be interpolated.
The values shown for properties which are not currently checked
are just the numerical properties of that differential property. In this image the curvature at
the targeted point term is 0, that is the curve is flat at this
point. Setting constraint
point image values by typing values is cumbersome. The normal way to modify these
values is with the mouse using a pick-and-drag interaction within the
ui-test graphical window as described below.
All the interactions executed through the VSLib
Test dialog box build and modify a minimization problem associated
with a simple starter shape.
After the problem is set up as one desires, click on the
<Solve Once> to see the affects. When the button is clicked the
minimization problem is built into a large matrix problem, that matrix
problem gets solved, and the solution of that problem gets shown as a
change in the current shape.
The <Dump> button is supposed to output a text
description of the current shape and its associated minimization
problem when clicked. It
is a known problem of this release that this function is currently
The <Done> button closes the VSLib Test
dialog box and ends the VSLib interaction.
Mouse I/O - Hot Points
One must use interactive mouse pick-and-drag
editing to understand the potential of designing shapes by modifying
point constraint parameters. The modification via the mouse is done
separately for each axis, starting with the x axis. A right mouse
click changes the mouse-axis to the y axis, then again to the z
axis, and back to the x axis again.
The ui-test graphical window supports Hot Point
objects. A hot point is a
location in the graphics window that can be moved by the mouse. Each time the hot point is
moved the underlying application is given a chance to respond to the
change. In VSLIb Test,
each time a hot point is moved all the modified target constraint
values are updated, the solver is called once, and the newly modified
shape is displayed on the screen. This happens fast enough to be
A hot point is assigned to every constraint value
that can be modified by the user. The next image shows for a
single shape the graphics for a hot point enabled just for position,
then for position and tangent, and finally for position, tangent,
normal direction, and curvature.
The image after this shows the change in shape made
by just modifying the tangent direction and secondly by just modifying
the curvature at the central control point.
The tangent and curvature values were modified in
these images by dragging the appropriate red colored hot points to new
All hot point motions are done with the left-mouse
button. There are
interactions for moving hot points which represent positions and for
moving hot points which represent vectors. Positions can be moved through
all of 3 space by moving the position along a line or within a
plane. Vectors can either
be rotated or lengthened.
Rotations happen about the hot point's base point and can
either be restricted to a circle within a 2d plane or restricted to a
hemisphere centered on the base point. Lengthening happen along the
vectors current direction
When the mouse is dragged over a hot point, a
tracking graphic is displayed.
Different graphics are displayed when dragging the hot point
along a line, within a plane, along a circular arc, or on a
hemisphere. At any one time two or three different kinds of drag
options, each with its own tracking graphic, are available for a hot
point. Only one of these options may be active at a time. The active tracking option is
indicated by color.
Active tracking graphics are displayed in cyan, inactive ones
in light grey. The active
tracking mode can be changed by clicking on a hot point with the left
mouse. Each click walks
through the set of available track modes. The next image shows the
tracking display for a position which can be tracked either within a
plane or along a vector.
The next figure shows a point that can be tracked
along a line or within a plane perpendicular to that line. The image in upper left shows
the point ready to be dragged across the plane while the image in the
lower left shows the point ready to go along the line. The two states toggle with one
another each time the mouse is clicked on the hot point.
The hot point is actually moved by clicking and
dragging it along its graphic as shown in the following figure.
There are additional graphics for moving vector end
points along circular arcs and over hemispheres. I never could decide when to
use which line and what plane to track a hot point. So I coded up several
variations that all can be seen by right-mouse clicking a
hot-point. Each time you
right click a hot-point the set of track options for the point
changes. By stepping
through the options you can get slide along x, y, or z axis options,
move in xy, yz, and zx planes and rotations about all the principle
So the general rule for controlling hot point
tracking is left-mouse click to change the current track mode and
right-mouse click to try out a different set of modes. All tracking is done by
left-mouse click and drag.
The general sequence for interacting with a VSLib
minimization model is summarized as:
- Get a
starting shape by clicking on the Curve, Surface, or Volume radio
- Add a
stiffness term - click the "Add Stiffness Term" button.
- Add corner
constraints to keep the shape from shrinking to a single point
solution - click the "Add Corner Constraints" button.
- Add a central
point constraint to give you something to track - click the "Add
Point Constraint" button.
- Target a
point constraint - drag the mouse over the hot point graphic for the
central point constraint.
This brings up the point term dialog box for the targeted
- Then try some
or all of the following things:
tracking the point constraint with just the position behavior to
see how the shape is changed.
- Turn on
the point constrain's tangent behavior in the point term dialog
box by clicking the image tangent check box and track the tangent
vector's length and orientation.
- Turn on
the point's curvature tangent behavior and change the curvature
value by tracking the length of the normal vector. It is a known problem that
the curvature value initially jumps to zero when you first try
this. You can work
around the problem by then lengthening the vector several times
(about 8) after which the interface begins to work properly again.
- Target the
stiffness term by clicking on the stiffness term item in the
display list to bring up the stiffness term dialog box. Try varying the alpha,
beta, gamma, and delta values by typing a new values into the
appropriate text boxes.
Once all the values are set, click the <Solve Once>
button to get a new solution shape. There are known interface
problems with setting the gamma and delta values. It is a known problem that
you can set all stiffness parameter values to zero and then call
solve. This won't
work but the interface does not stop you from doing it.
VSLib is implemented in a C++ class hierarchy and
one could program directly to the methods of those classes. However, that's quite
difficult requiring the programmer to know a lot about VSLib
VSLib also supports a functional API interface
which is implemented in files, /VSLib/VsMap/src/vsmapapi.h and
The API functions are all documented within the .h header files
and rather than reproducing that information here I'll leave it to the
reader to look them up.
The expectation is that all VSLib applications will
be written exclusively to the API interface
VSLib Test is my first shot at writing a
sophisticated Windows based pick and drag interface. All the features I wanted to
have are working in the implementation but some various combinations
of I/O confuse the interface.
These odd behaviors are just beginner bugs and will be
identified and removed in the near future.
I don't like most of the tracking graphics that
I've created. However
that's not very important and probably won't change unless someone has
a good suggestion for improving the hot point tracking look.
The VSLib solver is too slow. I tried building an optimized
Gauss elimination solver to treat all the constraint types in a
general fashion. I had
hoped that the choice would not show up in slower run times but it
does because my initial guess for the ratio of constraint equations to
stiffness equations was way too low. In the future I'm going to
modify the current solver to implement constraints by constraint space
projection. That will
take more time to set up, but will run faster supporting a much better
level of interactive pick-and-drag interaction. After which, I'm going to
build a second solver based on the iterative multi-grid method
modified to handle the class of constraints used in VSLib. In the end I expect this final
solver to replace the current solver altogether after its proven
faster and reliable.
Curve (and surface) constraints will be available
in the next release.
The approximation functions required to complete
the 3d Field Shaping application will be available in the next
release. However, one can
use the existing NLib approximation functions to build that
application now. Those
calls can be swapped out when the new VSLib approximation functions
become available if desired.