User Manual

Next:BibliographyUp:SvLis IntroductionPrevious:Afterword

Subsections

SvLis User Manual

Introduction

This manual contains a description of all of svLis's procedures, functions, and operators. It is intended as a stand-alone description for reference by those already familiar with svLis, either through having read this book on it or through having used the software, or both.

SvLis is a set-theoretic geometric modeller written in C++ that uses object-orientation and operator and function overloading to allow geometric computing to be done efficiently.

On the question of operators, I use $\wedge$ for a few things (e.g. exponentiation, symmetric difference) that usually bind quite tightly under normal arithmetical rules. The $\wedge$ (XOR) operator has pretty low precedence in C/C++ (lower than +, for example). As C++ doesn't allow one to change operator precedence, you have to use brackets.

Before calling any other svLis procedures, you must call the function

void svlis_init()

to get things started. There is a corresponding int svlis_end(int i) function that copies its argument to its return value, so the broad pattern of a svLis program is:

#include "svlis.h"
int main()
{
    svlis_init();
// ... Do some work with svLis ...
// An error exit:
    if(things_have_gone_horribly_wrong()) return(svlis_end(1)); // Or any non-0 value
// A successful exit:
    return(svlis_end(0));
}

The files mentioned in the descriptions below reside in three sub-directories beneath whichever directory svLis is installed in on your system. The directory include contains the .h files, and the directory sv_user contains user-modifiable C++ source code (which always, in svLis has the extension .cxx). If you have a source-code licence, other source code resides in the directory .src, otherwise these files will not be available to you and will only exist in compiled form in a library. Files that are always available are in red in what follows.

In all the descriptions below, the arguments of functions are, of course, given their types--for example

plane_line(sv_plane f, sv_line l).

In almost all cases the actual functions acquire their arguments by reference:

plane_line(const sv_plane& f, const sv_line& l)

This is more efficient for classes and structures (it saves a lot of copying), but would make this documentation cumbersome to read (and to write...) so it has been left out here; if you really need to know, look at the appropriate .h files.

In almost all cases, the member functions of svLis classes leave the parent object unaffected--they are const functions--and return a new object which is the result of applying the function to the parent object. Thus one often writes code like:

sv_model ma, mb;

// ...

mb = ma.facet();

in order to retain the original object (ma) and to generate a new one (mb). However, it is equally common to write

ma = ma.facet();

which overwrites the original. SvLis's internal memory management makes such overwriting very efficient.

Errors

Whenever svLis detects an error it calls an error-handling procedure:

void svlis_error(char* p, char* mess, sv_err level)

This procedure is user-modifiable (it is in the file sve.cxx), so you can write your own error handler if you want. The string p is the name of the procedure in which the error occurred, the string mess is a message that describes the mess, and level is an indication of severity. The severities are (in increasing magnitude of catastrophe):

SV_DEBUG,
SV_COMMENT,
SV_WARNING,
SV_FATAL, and
SV_CORRUPT

As svlis_error is supplied, it allows you to call the procedure

set_sv_e_lev(sv_err l)

with one of these severities as its argument; errors below the level that you set will not be reported; the default level at which you start to hear about things is SV_WARNING.

Now matter how severe the error is that has occurred, the as-supplied svlis_error always returns. If you want you can change this, but svLis generally takes the view that users should be allowed to go to hell in their own way, as long as svLis points out what road they're on; so such a change would be rather at odds with the rest of the software.

There are a lot of occasions in svLis when you can attempt operations which may fail (such as trying to find the line of intersection between two parallel planes, for example) but which are not errors. The function you have called will always return (if your actual data are dud, such as when one of the planes has a zero-length normal vector, svlis_error will be called first) but a flag value will be recorded. You can get at this by calling

sv_err get_svlis_flag()

This returns a flag_val (which is defined in enum_def.h). If your calculation worked as planned, you get 0 back; if something went wrong you get a value indicating what the trouble was. So you should write code like:

flag_val dud;
// ....
x = chancy_function(my_data);
if ( dud = get_svlis_flag() )
{
  cerr << "Hmmm.  That didn't work." << "Flag was: " << dud << '\n';
  // ....
} else
{
  // ....
}

Some functions return the flag value as an argument too (see below), but the value is always recorded for get_svlis_flag() as well.

Classes and functions

This describes each svLis class (or struct) and its associated functions and operators. It is divided up in much the same way as the source-code files; see the header (.h) files for less transparent but more complete explanations.

If you can't be bothered to figure out which .h files to include, then include svlis.h, which pulls them all in.

All the svLis structs and classes have the << and >> operators defined for output and input to ostreams and istreams . These are not primarily intended to produce user-readable output, but output in a form that can be read back in and checked by svLis. However, if you call the procedure

void pretty_print(1)

output will then be indented, and is reasonably easy to interpret. Calling

pretty_print(0)

turns off indented output (this is the default state), which makes the output less legible but about 30% more compact. SvLis can read in both indented and unindented files, of course. Even unindented files aren't all that compact--that's why we have programs like gzip and winzip--though even uncompressed they are much more compact than a boundary-representation data file.

Some of the data structures that svLis creates are very complicated. All of this complexity is retained across a single write or read. However, if you write out two things separately that were related, then that relationship will be lost when they are separately read back in. A good general rule is to write out the highest-level structure that incorporates everything you want.

Sums

Files: sums.h, enum_def.h, sums.cxx

These macros, functions and procedures implement constant definitions and some simple arithmetical operations.

Types sv_real and sv_integer are #defined to be float and long, and are used in almost all svLis declarations. This makes it easier to switch to double or int should the need arise. Here are the functions sums defines:

See also the sv_plane::range(sv_box b) function.

The include file enum_def.h contains #defines for three sv_planes:SV_XP, SV_YP, and SV_ZP which are the (y, z), (x, z) and (x, y) planes respectively.

sv_primitive sv_primitive::child_2(); sv_primitive sv_primitive::grad_y(),; sv_primitive sv_primitive::grad_z(); sv_primitive sv_primitive::deep(); long sv_primitive::unique()

There are functions to build the natural quadrics, the torus and the cyclide:

sv_primitive p_cylinder(sv_line l, sv_real r): is a cylinder with the line as its axis and the real as its radius.
sv_primitive p_cone(sv_line l, sv_real a): is a cone with line as the axis. The sv_real a is the cone's included angle in radians. The apex of the cone is at the line's origin. Note that this constructs the equation of a double cone meeting at the apex. If you only want half of it (and you probably do) then you have to turn it into a set (see Page ) and intersect it with a plane through the apex.
sv_primitive p_sphere(sv_point p, sv_real r): is a sphere; the arguments are its centre and radius respectively.
sv_primitive p_torus(sv_line l, sv_real big_r, sv_real little_r)
sv_primitive p_cyclide(sv_line l, sv_point sym, sv_real big_r, sv_real little_r, sv_real rc)

All these special shapes are flagged, and you can identify them for primitive p by calling p.kind(). If you make a natural quadric or a torus by multiplying the appropriate planes and reals together, svLis won't know that it is one, of course. Use the special functions whenever you need the special shapes.

If you call

void real_distance(1); it sets an internal flag that ensures that the common quadrics use the s_sqrt function to make their potential values reflect true distance. The default is real_distance(0), which will cause these functions to return their usual (that is, squared) distance potential.

A number of functions are provided for doing things with primitives. Note that adding or subtracting a point (i.e. a translation), spin, mirror, and complement all preserve the special shapes just described, and the internal flag is kept appropriately. You can treat the special shapes as ordinary primitives and do things like forming the product of a sphere and a cone. The product will be an SV_GENERAL, but its children will retain the flags for their special shapes. Here are the functions:

int p_thin(sv_primitive p)

The `sv_set` class

sv_integer sv_set::exists()

sv_set sv_set::deep(); long sv_set::unique()

sv_set cuboid(sv_box b)

There is also a collection of such functions that return surface-primitive sets called thin_cylinder and so on. They have exactly the same arguments as the functions listed above.

A number of utilities work with sets:

mem_test sv_set::member(sv_point p, sv_primitive known_surface[])
mem_test sv_set::member(sv_point p): performs a membership test classifying the point against the set. If you know that the point is on the SV_SURFACE of one or more primitives (for example, if it was generated by a ray-test into them), then call the first of these functions and list them in the array known_surface[]--this will ensure that the set regularization works properly and efficiently. Terminate the list with an undefined primitive. If there are no known surfaces call the second function.
sv_set sv_set::prune(sv_box b): prunes the set to the box, returning a set that is, in general, simpler than the original and which can validly represent it only inside the box.
void regular_prune(sv_integer p): Calling this with a true value for p forces the pruner to call the regularize() function for the sets it creates. A false value turns this behavior off; this is the default.
sv_set sv_set::spin(sv_line l, sv_real a): rotates the set about the line through an angle a.
sv_set sv_set::mirror(sv_plane m): returns the mirror image of the set in m.
sv_set sv_set::scale(sv_point c, sv_real s): scales the set about the point c by factor s.
sv_set sv_set::scale(sv_line axis, sv_real s)
prim_op same(sv_set a, sv_set b): tells you if two sets are the same within tolerance. This, like its overloaded equivalent for primitives, is a conservative function. It walks the trees, comparing them, and applies the same function to the primitives at the leaves. Note that the set same function is purely concerned with geometry; it completely ignores any attribute information.
sv_real s_set::value(sv_point p, sv_set* winner): returns the potential corresponding to a point. Recollecting the convention that inside a primitive is where its potential is negative and outside is where it's positive, the & operation is the same as the maximum of the potentials of its operands (that is it goes positive when either of them do, and is only negative when both are), and the | operation is the same as the minimum (when either operand giving a negative results in a negative). You may need to think about this a bit, and maybe draw a Venn diagram. The value function applies this equivalence to a set, and returns the resulting potential value, and the leaf set (i.e. the primitive) that gave rise to it (in *winner). This is rather slower than doing a membership test of the point, but it gives you more information.
sv_intervalsv_set::range(sv_box b, sv_set* w_lo, sv_set* w_hi)
sv_point sv_set::grad(const sv_point& p, sv_real& v)
sv_integer sv_set::max_degree(): returns the maximum degree out of all the primitives in the set.
sv_set sv_set::disjunctive_form(): This returns a new set that is the set in its disjunctive form (that is, it distributes unions over intersections). Note that this is an exponentially-hard problem, so don't do it for sets with a contents much bigger than, say, 10, unless you want to wait a while and use lots of memory.
sv_set_list sv_set::list_products(): This returns a list that is the disjunctive form (see above) of the set split into its intersected components. In other words all the unions in the disjunctive form have been thrown away, and you've got a list where each list entry is a component that just contains intersections.
sv_set sv_set::colour(sv_point col): attaches a colour to a set using attributes. The red, green, and blue values for the colour should lie between 0 and 1. Red is supplied in col.x, green in col.y, and blue in col.z.
sv_point sv_set::colour(): returns the colour of a set (if you've attached one; if you haven't you get a default medium grey back).
sv_set sv_set::name(char* str): attaches a string pointer to a set using attributes.
char* sv_set::name(): returns the text string associated with a set (if you've attached one; if you haven't you get a 0 pointer back).
sv_set sv_set::surface(sv_surface sf): attaches surface characteristics (see the sv_surface class on page ) to a set using attributes.
sv_surface sv_set::surface(): returns the surface associated with a set (if you've attached one; if you haven't you get the default surface back).
sv_set sv_set::polygon(sv_p_gon* pg): attaches a polygon pointer (see Page ) to a set using attributes. This is not normally called by the user.

sv_integer sv_set::polygon_count(): returns a count of the polygons attached to the set as attributes.
sv_p_gon* sv_set::polygon(): returns the polygon pointer associated with a set (if you've attached one; if you haven't you get a 0 pointer back). Note that if there is more than one polygon attached to a set in its attribute list, this only gives you back the first one; if you want them all, you have to retrieve the set's attributes and scan through them looking for polygons.

For details of how to attach attributes in general to a set, see the next section.

The `sv_attribute` class

Files: attrib.h, attrib.cxx, u_attrib.cxx

Attributes are a collection of integer tag values and pointers to a user-defined class called sv_user_attribute, terminated by a null attribute. You can, of course, add your own kinds of attribute. See the files u_attrib.h and u_attrib.cxx for details. Attributes are attached to sets.

sv_attribute a = sv_attribute(sv_integer tag);

makes an attribute with just the tag value supplied (i.e. with no user attribute), and

sv_attribute a = sv_attribute(sv_integer tag, new sv_user_attribute((void*) my_pointer));

makes an attribute with an sv_user_attribute associated with it. The pointer my_pointer can be a pointer to anything you like. The files u_attrib.hand u_attrib.cxxcontain the definition of sv_user_attribute which you can extend to suit your own needs; svLis uses the user-attributes already defined in those files, so modify those parts at your peril.
The set member function

sv_set sv_set::attribute(sv_attribute a);

returns a copy of the set with the attribute attached. Any old attributes will be retained by the original set, but replaced in the copy. The function

sv_attribute sv_set::attribute();

returns the attributes of a set.

Attributes form a linked list, and the same type of thing may be recorded in different places in the list. Suppose, for example, that you wanted to extract all the polygons from an attribute. You would write code like:

sv_attribute a;
sv_user_attribute u;
sv_p_gon* pg;

a = get_attribute_from_somewhere();

while(a.exists())
{
    if(a.tag_val() == -pg->tag())
    {
          u = a.user_attribute();
          pg = (sv_p_gon*)u->pointer;

          // Do whatever you want with
          // polygon pg.
    }
    a = a.next();
}

Note that the tag used to identify the attribute is minus the svLis tag value for the entity. All svLis types used as attributes use their own tags in this way. Positive tags are reserved for the user to employ.

The rules for attribute inheritance are simple: an attribute list for a set is recursively inherited by all children (i.e. operands) of that set that don't themselves have attributes. As soon as a child is encountered that has an attribute list, then that attribute list becomes the one inherited by all that set's children.

It may well be the case that when you union or intersect two sets, or you transform them, you also want to do something with the attributes attached to them (particularly if those attributes contain geometrical information). The following functions (defined in u_attrib.cxxso you can alter them) do nothing but return the set result in their form as distributed. But you can change them to pick up the attributes of the result or original sets and do whatever you like. Every time a set is unioned or intersected or transformed by svLis the appropriate procedure will be called for you.

sv_set att_union(sv_set result, sv_set arg_1, sv_set arg_2)
sv_set att_intersection(sv_set result, sv_set arg_1, sv_set arg_2)
sv_set att_slide(sv_set result, sv_set arg_1, sv_point arg_2)
sv_set att_spin(sv_set result, sv_set arg_1, sv_line arg_2, sv_real arg_3)
sv_set att_mirror(sv_set result, sv_set arg_1, sv_plane arg_2)
sv_set att_scale(sv_set result, sv_set arg_1, sv_point arg_2, sv_real arg_3)
sv_set att_prune(sv_set result, sv_set arg_1, sv_box arg_2)
sv_set att_complement(sv_set result, sv_set arg_1): is called whenever a set is complemented.

Here are the other attribute functions:

sv_attribute merge(sv_attribute a, sv_attribute b)
sv_attribute overlap(sv_attribute a, sv_attribute b)
sv_attribute overlap(sv_attribute a, sv_integer t)
sv_attribute remove(sv_attribute a, sv_attribute b)
sv_attribute remove(sv_attribute a, sv_integer t)
sv_attribute ex_or(sv_set_list a, sv_set_list b)
sv_attribute sv_attribute::replace(sv_attribute a)
sv_user_attribute sv_attribute::user_attribute()
sv_attribute sv_attribute::tag_find(sv_integer t)
void sv_attribute::set_flags(sv_integer i)
sv_integer sv_attribute::flags()
void sv_attribute::reset_flags(sv_integer i)
sv_attribute sv_attribute::deep()
long sv_attribute::unique()
sv_integer sv_attribute::tag_val()
sv_integer sv_attribute::tag()
sv_integer sv_attribute::exists()
sv_attribute sv_attribute::next()

The == and != operators are defined for attributes. Two attributes are equal if each list contains exactly the same attributes and tags (though they may not come out in the same order from the next function); otherwise they are not equal.

sv_integer sv_attribute::count(): returns the number of attributes in the collection (which may be 0, of course).
sv_attribute sv_attribute::tag_find(sv_integer tag)
sv_integer sv_set::has_attribute(): returns true if the set has an attribute, false otherwise.
sv_attribute sv_set::attribute(): returns the attribute of a set (if any). Check with s.has_attribute() first, or check the result with exists().
sv_set sv_set::attribute(sv_attribute a)
sv_set sv_set::strip_attributes(): returns a copy of the set with all its attributes stripped off.
sv_attribute sv_set::inherit(sv_set node): resolves attribute inheritance. The set node is the one you want to know the attribute of. The set for which the function has been called contains node somewhere in its tree. This function searches that set tree keeping track of attributes, and tells you the attribute that node has. If s.inherit() returns a non-existent attribute, node either had no attribute or the required one wasn't in the tree below s. In general, it is better to run the percolate() function once (see below) to find the inherited attribute of a set in the middle of the tree if you wish to do that several times--it's more efficient. Only use inheritfor isolated queries.
sv_set sv_set::percolate(): percolate returns a copy of the set with all its attributes copied down to all the nodes that inherit them. Note that, as attributes use svLis's usual pointer and reference count scheme, this is pretty efficient, and doesn't use much more memory than the unpercolated set. When you've finished building a set it's usually a good idea to call this function before doing anything with it like rendering it or whatever.

The `sv_set_list` class

Files: set.h, set.cxx

The class sv_set_list maintains lists of sets. You start a list off with a single set:

sv_set_list sl = sv_set_list(sv_set s);

The main use of lists of sets is in the sv_model class. The following functions are provided for lists of sets:

sv_set_list merge(sv_set_list a, sv_set_list b): merges the lists a and b to form their union. Common sets will appear only once in the result, thus it is not possible to have a set list with more than one copy of a set in. Sets are considered different if their attributes are different, so the same geometry can appear more than once. As there is a constructor for making a set list from a set, you can put a single set as either or both arguments instead of a set list. This is also true for the following three functions.
sv_set_list overlap(sv_set_list a, sv_set_list b): intersects the lists a and b. The result may be null, of course--test this with the exists() member function below.
sv_set_list remove(sv_set_list a, sv_set_list b): removes any sets that are in bfrom the list a.
sv_set_list ex_or(sv_set_list a, sv_set_list b): does an exclusive OR on the two lists--the same as the symmetric difference.
void sv_set_list::set_flags(sv_integer i): and the following two functions work in exactly the same way as their overloaded equivalent functions do for primitives, sets, and attributes.
sv_integer sv_set_list::flags()
void sv_set_list::reset_flags(sv_integer i)
long sv_set_list::unique()
sv_set sv_set_list::set(): returns the first set in the list.
sv_integer sv_set_list::exists(): returns true if the list exists, false otherwise.
sv_set_list sv_set_list::next(): returns the next item in the list. To get all the individual sets out of a list, sl, you would write code like:
sv_integer sv_set_list::count(): returns a count of the number of sets in the list.
sv_integer sv_set_list::contents(): returns the total of all the contents values for all the sets in a list. Sets that are SV_EVERYTHING and SV_NOTHING both contribute zero, so this is effectively a count of the number of primitives that go to make up all the sets in the list.
sv_set_list sv_set_list::prune(sv_box b): prunes each set in the list to the box using the set prune function, returning a list of the resulting sets. Sets that are (or which become) SV_NOTHING or SV_EVERYTHING will be retained.
sv_point sv_set_list::point(): returns the characteristic point of a set list. This is defined to be the point which minimizes the sum of squared distances to all the planes that are in the sets' primitives' expressions. See the same function for sets (page ) for a fuller explanation.
sv_integer sv_set_list::tag(): returns the unique svLis tag of lists of sets.
sv_set_list sv_set_list::percolate(): returns a copy of the set list with all its sets' attributes copied down to all the nodes that inherit them.
sv_set_list sv_set_list::deep(): returns a deep copy of the set list. The user shouldn't normally call this function.
sv_integer sv_set_list::max_degree(): returns the maximum degree out of all the primitives in all the sets in the list.
sv_integer sv_set_list::polygon_count(): returns the number of polygons attached as attributes to all the sets in the list.
sv_set sv_set_list::unite(): returns a single set that is all the sets in the list unioned together. See also the list_products() function.
sv_set sv_set_list::intersect(): returns a single set that is all the sets in the list intersected together.

Two lists of sets are equal (sla == slb) if their individual sets are equal with equal attributes in any order. The

prim_op same(sv_set_list a, sv_set_list b)

function returns SV_PLUS if the sets in the list are the same in any order, SV_COMP if all the sets in b are complements of the corresponding sets in a, and SV_ZERO otherwise. The same function ignores attributes--it is only concerned with geometry.

The `sv_model` class

Files: model.h, model.cxx

A model is a list of sets in a box. Models can be divided in two, making two boxes that join in a plane perpendicular to one of the coordinate directions, each of which contain a list of sets that is a pruned (that is, simplified) version of the original list of sets in the original box. This division is normally done recursively, leading to lots of little boxes that fill the original big box in a binary tree, each little box containing something very simple indeed (like SV_NOTHING, or the union of just two leaf sets, or SV_EVERYTHING and so on). This recursive division is the very heart of svLis, and is what makes the whole modeller tractable and efficient.

Fairly obviously, it is possible to make a model from a set list and a box by writing:

sv_model m = sv_model(sv_set_list sl, sv_box b);

The list of sets is pruned to the box using prune(). The function

sv_model(sv_set_list sl, sv_box b, LEAF_M)

suppresses the pruning, and ensures that the model contains exactly sl. Most of the time, you'll probably only have one set in the list. C++ is smart enough to spot that there's a constructor for building a list of sets from a single set, so you can say

sv_model m = sv_model(sv_set s, sv_box b)

in this case. There are also the following constructors for when the model you create is part of a tree of models and you know the parent node in the tree:

sv_model(sv_set_list sl, sv_box b, sv_model parent)
sv_model(sv_set_list sl, sv_box b, LEAF_M, sv_model parent)

Like the other `complicated' types, sv_model hides its data, and functions are provided to get at it:

sv_model sv_model::parent(); sv_model sv_model::deep()

The following are functions that act on models:

sv_model sv_model::divide(void *vp, void decision(...) ): recursively divides a model employing a user-supplied decision procedure, of which more in a moment. The pointer vp is passed on to the decision procedure to allow you to send in any data you like.
sv_model sv_model::redivide(sv_set_list sl, void *vp, void decision(...) )
void sv_model::div_stat_report(ostream& f): sends a report on all sorts of statistics about a divided model to f(which you usually want to be cout). This is useful for debugging divider procedures.
sv_box sv_model::tight_fit()

The user-supplied divider decision procedure mentioned above has the following form:

void decision(sv_model m, sv_integer level, void *vp,
              mod_kind* k, sv_real* coord,
              sv_model* c_1, sv_model* c_2)

This should decide whether to divide m. If m is not worth dividing, *k should be set to LEAF_M on return. If m should be divided, then k should be set to one of X_DIV, Y_DIV, or Z_DIV to indicate which direction the model is to be divided in, and *coord should be set to the coordinate value where the split is to be (which must, obviously, be in the range specified by m's box). The value of level tells your decision procedure how far down the tree the division has got. The top (root) level is 0, and this is incremented for each level down. There is a

sv_model root_model();

function that your decision procedure can call to find out what the root model was that is currently being divided. The pointer vp is the pointer that you passed to divide(...) (or whichever); it allows you to send in any data that you like, or indeed to retrieve any.

It may well be the case that, in order to make this decision, your procedure has to work out what the resulting children will be. If it does, it can return either or both of them in *c_1 and *c_2--this will save divide the trouble of recomputing the information. If it doesn't, it must not alter these pointers. If it decides that the model is a leaf, but it is necessary to alter it anyway (for example by faceting it), then it can return the new leaf model in *c_1.

A rather naïve decision procedure is provided in the files decision.h and decision.cxx called dumb_decision. It is intended primarily as a template on which you can base your own divider decision procedures, but to use it you write

sv_model a = ....;
// ....
sv_model b = a.divide(0, &dumb_decision);

The procedure dumb_decision causes divide to split the model in half recursively along the longest sides of boxes, until either the sets in the boxes have a contents value less than the value returned by sv_integer user_low_contents() or the boxes have a volume lower than the one returned by sv_real user_little_box(). Both these functions have to be provided by you; there are example ones in the files decision.h and decision.cxx--see these to find out how to alter these values. Reasonable values for user_low_contents() to return are 3 or 4, and 0.001 times the volume of the undivided model box is okay for user_little_box(). Check what sort of results you get with b.div_stat_report(cout).

There is also a smart_decision procedure which does divide look-ahead. You can set it up either to minimize the maximum contents of the resulting divided boxes (tends to even out complexity) or to minimize the minimum (tends to localize complexity). There are a couple of procedures called

set_smart_strategy(sv_integer s)

and

sv_integer get_smart_strategy()

that select and return this if called before dividing commences. The value of s should be one of SV_MIN_MAX or SV_MIN_MIN.

Be warned, it often turns out that the dumb_decision procedure is smarter than the smart_decision one.... Experiment.

The << and >> operators are defined for sending models to streams and getting them back, and these work both for divided and for undivided models, of course. However, there is little point in writing and reading divided models as the model divider is faster than file access. It is always quicker to write the undivided model, and to read that in and re-divide it.

When models are split in two the resulting boxes are swollen by a factor to ensure that no information falls down the cracks. The default factor is DEF_SWELL_FAC which is defined in enum_def.h . You can change the value (including setting it to 0; negative values are not recommended....) by calling

set_swell_fac(sv_real fac)

where fac is the value you want. The function

sv_real get_swell_fac()

returns the current value.

The svLis model class has a number of member functions for graphics:

void sv_to_vrml(ostream& os, sv_model m); void sv_to_vrml(char* filename, sv_model m)

The `sv_surface` class

void sv_surface::map_origin(sv_point p); void sv_surface::map_u(sv_point p); void sv_surface::map_size(sv_point p)

There are a corresponding series of sv_surface member functions with no arguments and the names above that return the values, points and so on set by those functions.

When the raytracer and polygon plotters are rendering a svLis model that has texture-mapped surfaces it makes calls to the user-modifiable function void get_tex_map(...) that decides the map. This is in surface.cxx. Texture mappings are defined for planes and cylinders, for which the projection is more-or-less obvious. You can add your own custom mappings for other surfaces.

void sv_picture::pixel(sv_integer x, sv_integer y, sv_pixel p)

There's a constructor for the sv_pixel struct that builds it from an sv_point:

sv_pixel p = sv_pixel(sv_point(red, green, blue));

The red, green and blue values are sv_reals in the range [0, 1]. The members of sv_pixel are called r,g, and b. They are of type GLubyte, which is an OpenGL definition for unsigned char. There is also a function to turn a pixel back into a point colour value:

sv_point sv_pixel::point();

The `sv_p_gon` struct

Files: polygon.h, polygon.cxx

In the next release of svLis (version 4) this structure will be included in the reference counting scheme, and instances of it will consequently not be passed using pointers.

A single polygon can represent a three-dimensional point-set , a polyline , or (naturally) a polygon. It consists of a linked list of points in space that usually, though not necessarily, lie in a plane. Polygons are used to approximate svLis models mainly for producing graphics.

Here are the data of the polygon structure:

struct sv_p_gon
{
  sv_point p;       // The point
  sv_point g;       // The grad at that point
  sv_p_gon* next;      // Link to the next one
  sv_integer flag;  // used for clipping
  sv_p_gon_kind kind;  // What it is

// Plus member functions ....

The value of kind can be one of PT_SET, P_LINE, or P_GON. These represent point sets, poly-lines, and polygons respectively. A polygon always forms a closed loop (i.e. successive values of next chain back to the start), even if it's really a polyline (in which case the last next is ignored), or a point set.

A number of functions are provided for dealing with polygons:

sv_p_gon* first_point(sv_point q, sv_p_gon_kind k): creates a new polygon of the appropriate kind containing a single point.
sv_p_gon* add_edge(sv_p_gon* pg, sv_point q): adds a point in the linked list after pg. The pointer returned is to the new point.
sv_integer p_gon_vertex_count(sv_p_gon* pg): returns the number of vertices in a polygon.
void set_p_gon_grad(sv_p_gon* pg, sv_primitive p): sets values of g for all the points in the polygon to a normalized grad vector to the primitive at that point. Displays and software that use Gouraud shading to depict curved surfaces can use this information to render the polygon.
void kill_p_gon(sv_p_gon* pg): returns the storage reserved for a polygon to the free space.
sv_p_gon* copy_p_gon(sv_p_gon* pg): returns a copy of a polygon.
sv_p_gon* copy_p_gon(sv_p_gon* pg, sv_p_gon_kind k): returns a copy of a polygon with its kind changed to k.
sv_point p_gon_tri_norm(sv_p_gon* pg): cycles through all the triangles that make up a polygon, adding up the vector product of their edges, which is returned. This is a sort of mean normal direction for the polygon, but, more importantly. . .
sv_real p_gon_area(sv_p_gon* pg): uses the above function to compute the polygon's area. The calculation is exact if the polygon is planar, approximate otherwise.
sv_integer sv_p_gon::tag()

Voronoi diagrams

Files: voronoi.h, voronoi.cxx

In the next release of svLis (version 4) these structures will be included in the reference counting scheme, and instances of them will consequently not be passed using pointers.

This is not the place to describe in detail what a Voronoi diagram and its associated structure a Delaunay triangulation are, but you may care to consult this reference. Neither are either of these structures a central part of svLis. However, facilities for computing them have been added to svLis as a precursor to the computation of medial-axis transforms and finite-element meshes. SvLis uses three data structures for Voronoi diagrams: a Delaunay structure that represents the points in the diagram, a vertex structure that represents an individual vertex in the diagram, and a Voronoi structure that represents the whole diagram. These are best explained in reverse order.

The sv_voronoi class

sv_voronoi::sv_voronoi()
sv_voronoi::sv_voronoi(sv_box bb);
sv_delaunay* sv_voronoi::add_point(sv_point p);
sv_vertex* sv_voronoi::walk_start()
sv_integer sv_voronoi::point_count()
sv_box sv_voronoi::box()
sv_delaunay* sv_voronoi::nearest(sv_point p);
sv_delaunay* sv_voronoi::neighbours(sv_delaunay* d);
sv_vertex* sv_voronoi::territory(sv_delaunay* d)
sv_vertex* sv_voronoi::contiguity(sv_delaunay* d0, sv_delaunay* d1)
int sv_voronoi::exists()
sv_integer sv_voronoi::tag()
void sv_voronoi::write(ostream&)
sv_voronoi tet_mesh(sv_model m, sv_real d)
void plot_voronoi(sv_voronoi v, char* title, sv_integer pv, sv_integer pd, sv_integer pp, sv_real tet_fac)
void plot_voronoi(sv_voronoi v)

The sv_vertex class

A Voronoi vertex is the circumcentre of a Delaunay tetrahedron.

void sv_vertex::set_flag(sv_integer f)
void sv_vertex::reset_flag(sv_integer f)
sv_integer sv_vertex::flag()
sv_delaunay* sv_vertex::delaunay(sv_integer i)
sv_vertex* sv_vertex::neighbour(sv_integer i)
sv_point sv_vertex::position()
sv_real sv_vertex::r_squared()
sv_point sv_vertex::centroid()
sv_vertex* sv_vertex::next()
int sv_vertex::infinity()
sv_integer sv_vertex::tag()
sv_vertex* find_enclosing_tet(sv_vertex* v, sv_point p);
void reset_flags(sv_vertex* v, sv_integer f);
sv_real tet_vol(sv_point k, sv_pointl, sv_point m, sv_point n)

The sv_delaunay class

This class holds the individual points that form the basis of the Voronoi diagram.

void sv_delaunay::set_flag(sv_integer f)
void sv_delaunay::reset_flag(sv_integer f)
sv_integer sv_delaunay::flag()
sv_point sv_delaunay::point()
void sv_delaunay::set(sv_set s)
sv_set sv_delaunay::set()
void sv_delaunay::model(sv_model m)
sv_model sv_delaunay::model()
sv_delaunay* sv_delaunay::next()
int sv_delaunay::c_hull()
sv_integer sv_delaunay::tag()

Utilities

Files: sv_util.h, sv_util.cxx

The svLis utilities are intended to be user-extendible, but a number are supplied as standard. They are:

void integral(sv_model m, sv_real accy, sv_real& vol, sv_point& centroid, sv_point& mxyz, sv_point& nxyz)
sv_real area(sv_model m): This procedure computes the surface area of the model, m, which must be a faceted model. It adds up the area of the facets. For accuracy, you should call set_swell_fac(0) before faceting the model.
sv_real area(sv_model m, sv_set a): This procedure computes the surface area that the set s contributes to the model, m, which must be a faceted model. It adds up the area of the facets. For accuracy, you should call set_swell_fac(0) before faceting the model.
sv_point ran_point(sv_box b): This generates a random point from the uniform distribution over the box.
sv_interval dist_2(sv_box a, sv_box b): This computes the interval representing the minimum and maximum squared distance between the two boxes. If the boxes overlap, the minimum is 0, of course. The function returns the value of the closest two points--one in each box--could get to each other, and the value when they are furthest apart.
sv_point newton(sv_primitive p, sv_point start, sv_real accy): This finds a point on the surface of the primitive using Newton-Raphson from point start. The value given in accy determines how finely the iteration runs.
sv_point newton(sv_set s, sv_point start, sv_real accy)
sv_point edge(sv_set s, sv_point start, sv_real accy): This finds a point on the edge formed by the intersection or union of two leaf sets using Newton-Raphson from point start. The value given in accydetermines how finely the iteration runs. Clearly s must be the union or intersection of two leaf sets.
sv_point edge_step(sv_set s, sv_point start, sv_point d, sv_real r, sv_real accy): This moves (roughly) distance r along the edge formed by the intersection or union of two leaf sets in (roughly) direction d using Newton-Raphson from point start [found by procedure edge(...)]. The value given in accy determines how finely the iteration runs. Clearly s must be the union or intersection of two leaf sets.
sv_point corner(sv_set s, sv_point start, sv_real accy): This finds the point of the corner formed by the intersection and/or union of three leaf sets using Newton-Raphson from point start. The value given in accy determines how finely the iteration runs. Clearly s must be a set-theoretic expression involving three leaf sets.
sv_point binary_chop(sv_primitive p, sv_point p0, sv_real v0, sv_point p1, sv_real v1, sv_real accy): This finds a zero of the primitive along the line between the two points p0 and p1. The value of v0 should be p.value(p0) and v1 should be p.value(p1)--clearly v0 and v1 should have opposite signs. The reason for requiring these values as arguments is that you almost always have to work them out before calling the procedure anyway, so your providing the results saves time. The value given in accy determines how finely the iteration runs. This procedure uses a binary chop (as its name implies) rather than Newton-Raphson, as this guarantees that the result will always lie between the two input points.
sv_plane box_face(sv_box b, sv_integer i): returns the ith face of the box as a plane. The value of ishould be between 0 and 5 inclusive.
sv_set wireframe_box(sv_box b): This constructs a set which is a wireframe representation of box b.
sv_real crinkliness(sv_model m)
sv_primitive slice(sv_plane f, sv_mod_kind k, sv_real d)
sv_primitive slice(sv_primitive p, sv_mod_kind k, sv_real d)
sv_set slice(sv_set s, sv_mod_kind k, sv_real d)
sv_set_list slice(sv_set_list sl, sv_mod_kind k, sv_real d)
sv_box slice(sv_box b, sv_mod_kind k, sv_real d)
sv_model slice(sv_model m, sv_mod_kind k, sv_real d)

If you write a new utility that you think would be helpful to other svLis users, email [email protected] with a brief description of it and we may include it in the next release.

SvLis programs

There are a number of programs provided with svLis. Their sources are in the directory programs under the main svLis directory, which has the following structure:

programs--
          |
          |-README
          |
          |-refinery--
          |           |
          |           |-src--
          |                  |
          |                  |-refinery.cxx
          |
          |-sv_edit--
          |          |
          |          |-src--
          |                 |
          |                 |-sv_edit.cxx
          |                 |-edittool.cxx
          |
          |-tst_prgs--
                      |
                      |-expt.cxx
                      |-sv_convert.cxx
                      |-sv_display.cxx
                      |-sv_tst_1.cxx
                      |-sv_tst_2.cxx
                      |-voronoi_tst.cxx The file README just gives information on what is in the programs directory. Each architecture supported by svLis has a mechanism provided in the distribution for creating executables from all the other programs. For Unix systems, just typing make will create executables for them all (it will also build the user library too); for Microsoft Windows installations there are Visual C++ project files for all the programs in the subdirectories of the projects directory; for Apple Macs there is a project file supplied to build all these programs (and a separate one for the user library). All the executables are placed in the bin directory under the main svLis directory.

This is what all the programs do:

sv_tst_1

When run this creates a simple model of a cube intersected with a sphere in the directory results. sv_tst_2

This reads the model created by sv_tst_1, divides it, and prints out some statistics on it. sv_tst_g

This reads the model created by sv_tst_1 and plots a picture of it. The graphics procedure runs as a separate thread, so you usually get a `program finished' message before the graphics window appears. voronoi_tst

This is a simple interactive program to build and plot Voronoi diagrams. Start it with the coordinates of the bottom and top corners of a box, then insert points into the diagram (or have the program insert random ones for you) then plot the results. The plot window menus have options to turn on and off the plotting of the points, the Delaunay triangles, and the Voronoi territories. refinery

When run, this creates the oil refinery model in the results directory. svlis

This is the result of compiling sv_edit.cxx and edittool.cxx. It is a text-driven interactive model editor that allows you to create, edit, view, and save svlis models. You should put the svlis program in the executables path on any machine upon which svLis is installed so that all users may run it. The svlis program has an option to dump an interactive session into a file, which it can then replay at a later date. Three such files exist in the data directory just under the main svLis directory called r_pic_ux.log, r_pic_ms.log and r_pic_mac.log for Unix, Microsoft, and Apple installations respectively. If you run svlis on the appropriate one of these it will ray-trace the refinery model (which you have to have created first, of course). sv_display

This displays a svlis model. Just type sv_display my_model.mod(or whatever the name of your model is) and this will create a picture of it. This program should be put in the executables path of any system on which svLis is installed so that all users can run it. Also, on Apple Macs and Microsoft systems, you should set the system up so that clicking on a .mod file runs this program with the file as input. You can achieve the same effect on Unix systems with utilities like Xfm. The svLis logo is provided in the data directory in various formats; if you wish, you can configure the system to use this as an icon for svLis .mod files. This program reads command line arguments, and so is not much use on a Mac, but it's included for completeness. You can of course edit it if you want. sv_convert

This updates svLis files from the previous version to the current version. It will update files containing svLis attributes, primitives, sets, set lists, or models. The current version is 3, so this will update svLis Version 2 files. However, If you build it under svLis Version 2 it should update Version 1 files; I have tried this and it works, but I have not tested it extensively. This program reads command line arguments, and so is not much use on a Mac, but it's included for completeness. You can of course edit it if you want. expt

This is just a test program that you can hack to try out quick svLis ideas. Just write your code into expt.cxx; the distribution provides you with a ready-made way of compiling and linking the executable, so you don't have to bother about how to get that right. If you want to start writing svLis code, the simplest thing to do is to copy one of the other test programs into expt.cxx, edit it, make it, run it, and see what happens.

Next:Bibliography Up:SvLis Introduction Previous:Afterword

Adrian Bowyer

User Manual

SvLis User Manual

Introduction

Errors

Classes and functions

Sums

Geometry

The `sv_point` struct

The `sv_line` struct

The `sv_plane` struct

The `sv_interval` and `sv_box` structs

The `sv_primitive` class

The `sv_set` class

The `sv_attribute` class

The `sv_set_list` class

The `sv_model` class

The `sv_surface` class

The `sv_view` class

The `sv_lightsource` and `sv_light_list`classes

The `sv_picture` class

The `sv_p_gon` struct

Voronoi diagrams

Utilities

SvLis programs

User Manual

SvLis User Manual

Introduction

Errors

Classes and functions

Sums

Geometry

The sv_point struct

The sv_line struct

The sv_plane struct

The sv_interval and sv_box structs

The sv_primitive class

The sv_set class

The sv_attribute class

The sv_set_list class

The sv_model class

The sv_surface class

The sv_view class

The sv_lightsource and sv_light_list classes

The sv_picture class

The sv_p_gon struct

Voronoi diagrams

Utilities

SvLis programs

The `sv_point` struct

The `sv_line` struct

The `sv_plane` struct

The `sv_interval` and `sv_box` structs

The `sv_primitive` class

The `sv_set` class

The `sv_attribute` class

The `sv_set_list` class

The `sv_model` class

The `sv_surface` class

The `sv_view` class

The `sv_lightsource` and `sv_light_list`classes

The `sv_picture` class

The `sv_p_gon` struct