VSLib Tutorial

 

Contents  

VSLib User Overview.

VSLib Test User Overview.

VSLib Programming Interface.

Known Release Problems.

 

VSLib User Overview

VSLib, The Virtual Shape Library, uses optimization algorithms to solve geometry shape problems.  In VSLib, optimization problems are an indirect way to find the shapes of curves, surfaces, and volumes.  It is indirect because the user specifies the desired shape by describing its desired properties rather than specifying its shape parameters.  For example, consider a line segment.  The direct way of designing that segment is to specify that the curve is a line with two given end-points.  The indirect way is to ask for the shortest curve possible that connects two end points.  Both approaches build the exact same line.

When working with free-form shapes that have large shape parameter counts like BSpline curves, surfaces, and volumes, the indirect method shines, giving users a friendly method of design that saves them from directly editing shape parameter values. 

VSLib is meant to be used as a recipe; follow the steps below in their given order to design a shape.

 

  1. Specify the starting shape (curve, surface, or volume).
  2. Specify a minimization problem.
  3. Specify a list of constraints that must be satisfied (point and curve constraints).
  4. Specify the parameters for each constraint, e.g. point locations for point constraints.

  5. Specify a list of desired properties. (smoothing terms, point and curve loads).
  6. Specify the parameters for each properties, i.e. the gains for resistance to stretch and resistance to bending.

  7. Solve the problem and review the solution shape.
  8. Optionally, enter a design loop.
    1. Review the shape - typically looking at a rendering.
    2. Add, Remove, or Modify one or more of the constraints or loads.
    3. Solve - and return to step 4a. until an acceptable shape is found.

VSLib is to be used by people who may or may not be familiar with the underlying math to easily define interesting and beautiful shapes.

VSLib Naming Conventions.  

VSLib is implemented in a C++ object hierarchy using templates so that the interface for curves, surfaces, or volumes is always the same.  All global functions start with the characters "VS_" followed by a camel capitalized description for the rest of the name, e.g. VS_GetMap().  All class names are camel capitalized and start with the characters "Vs" to make them unique in a user application, e.g. VsBoolean and VsErr.  All class names which are templated for curves, surfaces, and volumes end in the characters "Nd," a pneumonic for multi-dimensional.  In coding to these classes you have to supply the desired domain dimension value as part of the class name.  For example, points are multi-dimensional in VSLib and are implemented in the class VsPointNd.  Code to declare 1, 2, and 3 dimensional points looks like the following:

   VsPointNd<1> sPoint1d ;

   VsPointNd<2> sPoint2d ;

   VsPointNd<3> sPoint3d ;

}

The character strings "<1>", "<2>", and "<3>" are part of the class names and are required by C++ when programming.   However in this document such classes are presented without these strings whenever the comment applies equally to all dimensions.

Starter Shapes

VSLib starts with a curve, surface, or volume shape description.   In VSLib shapes are represented parametrically and as such are called maps since they map a set of points from a domain space to a set of points in an image space as:

Domain Space Points -> Map -> Image Space Points.

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. 

Minimization Problems

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 minimization problems.  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.

Minimization Terms

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.

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.

Default Shapes

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.

Smoothing Terms

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 below.

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

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

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 solution.  Many 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.

Gamma

(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.

Delta

(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.

Constraints

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 control points.

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 shape.

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 G2 continuity.

Loads

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 constructed.

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 parameters.

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 tolerance.

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 use.

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: 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 shape.

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:

  1. Smoothing 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.
  2. Point 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.
  3. Curve Constraint Terms - to force the solution shape to interpolate an infinite number of points situated along a curve within the shape.
  4. Point Load Terms - to make the solution shape approximate a set of point locations.  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.
  5. Curve Load Terms - to force the solution shape to approximate an infinite number of points situated along a curve within the shape.
  6. 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.
  7. Default Shapes - Default shapes allow an application to make small smooth deformations to an existing shape such as in healing or in re-engineering applications.

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:

  1. There are many fewer minimization terms and parameters to vary than control-points in a free-form shape minimization model.
  2. The 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.
  3. Each 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 section.

 

VSLib Test User Overview

 

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.

3d Field 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.

  1. Read in your favorite BRep model.
  2. Click the "3d Field Shaping" check box on.
  3. Create a starter Volume by clicking the Volume radio button.
  4. Add a stiffness term, corner point constraints, and a central point constraint by clicking the appropriate buttons once as described later in this document.
  5. 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.
  6. Known problems: 
    1. 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 problems. 
    2. The 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.
    3. Upon 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 list box.

 

 

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 constraints.

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 stiffness. 

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 broken. 

The <Done> button closes the VSLib Test dialog box and ends the VSLib interaction.

VSLib Test 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 interactive.

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 positions. 

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 axes.

 

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:

  1. Get a starting shape by clicking on the Curve, Surface, or Volume radio button.
  2. Add a stiffness term - click the "Add Stiffness Term" button.
  3. Add corner constraints to keep the shape from shrinking to a single point solution - click the "Add Corner Constraints" button.
  4. Add a central point constraint to give you something to track - click the "Add Point Constraint" button.
  5. 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 constraint.
  6. Then try some or all of the following things:
    1. Try tracking the point constraint with just the position behavior to see how the shape is changed.
    2. 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.
    3. 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.
    4. 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 Programming Interface

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 internals. 

VSLib also supports a functional API interface which is implemented in files, /VSLib/VsMap/src/vsmapapi.h and /VSLib/VsQMin/src/vsqminapi.h.  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

Future Features and Known Problems

 

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.


Legal Stuff

All of the software and documentation received with this release is copyrighted by Solid Modeling Solutions, Inc. You may not distribute source code or documentation for this software outside of the company and the site which owns the license. The standard license agreement allows you to freely distribute object code in any application which does not contain a programmatic interface. All software and documentation is considered proprietary information and the intellectual property of Solid Modeling Solutions, Inc. This document contains trade secret information which is deemed proprietary.

Copyright 1998-2010 Solid Modeling Solutions All rights reserved.
Information in this document is subject to change without notice.