                              Sweep Convert Usages Quick Start


	This is a quick start guide for using sweepconvert.pl which was included with the zip
file for the "Opportunity Passing..." image of the Loneliness round in the IRTC. It gives
you enough basic info to get you using sweepconvert.pl, and no frills to spare (because I'm
writing it at the last minute!)

	To use sweepconvert.pl, your system must already have a perl interpreter installed. 
If you don't, check out http://www.ActiveState.com/ for ActivePerl, a version of perl I've
used on my own machine for several months and can recommend. The sweepconvert.pl file is just
the actual perl code itself. Once you have your perl interpreter installed and configured,
continue with this guide.

	Sweepconvert was designed to take the output of Moray, parse out specially named spheres
group/unions, and boxes and turn them into sphere sweeps in UDO/INC pairs that allow you to
reintegrated the finished results back into a Moray scene easily. 

CHOOSING THE SPLINE TYPE 

To begin: Create a Moray file and call it "sweeps.mdl" (doesn't matter what you call it, that
is just and example). In that scene file, create a CSG Union and give it the following name:

                SweepA_cubic_spline

The format of the name is very important. The "cubic_spline" part you will recognize as being
what you need to tell POV when you identify the type of spline to use in your sweep (if you've
read up on sphere_sweeps in the POV docs, which you should have! :) ) The part at the beginning
is just a name to assign to the sphere sweep. The only restriction is that it must follow the
normal POV object naming conventions. That is, using only letters, numbers and underscores, 
and must be 40 characters or less. I recommend not using underscores, since, as you see, they
are already used to keep apart the pieces of the sweep name in the Moray Union, and this 
ecomes visually confusing. 

	More examples:

	"SliderThing_linear_spline" creates a linear_spline sweep called "SliderThing"

	"Coily_b_spline" creates a b_spline called "Coily"

You can create multiple unions with different sweep names in one mdl file, and sweep convert
will make a multi-part UDO/INC pair which converts all the sweeps at once into a single UDO
object. This can be especially helpful if you want two or more sweeps to interact with one
another in your scene or can't make a shape out of just a single sweep. 


CONTROL POINTS

Into this union, you will place specially named sphere objects. They must be spheres, and they
must be named as I will show below in order for sweepconvert.pl to locate them and know you
meant for them to be control points. Technically, they do NOT have to be in the union at all,
but since Moray displays unions as heirarchical groupings, it's easier to read your work if
you group all your control points this way. 

The way to name your first sphere is as follows...

	cp_SweepA_1

There are three pieces to this name: "cp_" identifies this as a sphere sweep control point. 
Without this prefix, sweepconvert will disregard it as an ordinary sphere, and not use it as
part of your sweep. This allows you to have things in your sweeps.mdl file that are NOT part 
of the sweep, which can be useful if you need another part of your scene as a reference by 
which to position your sweep. 

The second part is just the name of the sweep. It is important that this match exactly the
name you gave to the Union earlier. When sweepconvert finds a control point, it uses the name
to decide which sweep to make it part of (the sweeps are stored temporarily in hashes keyed
with the name of each sweep). If the name doesn't match, perl doesn't sweat. It just makes a
new sweep and sticks this control point in that instead. This prevents a crash of the script,
but it isn't what you wanted, so use caution here.

The number at the end can be anything, really, as long as it is preceded by the underscore.
Sweepconvert genuinely doesn't care what you put here. It's just something to make the Moray
assigned name unique, since Moray doesn't let you name two objects with the same name. The
reason I recommend a number is simply that Moray's automatic naming system will increment this
numeral every time you use copy/paste or duplicate on this object, so you end up creating a
bunch of unique names that are logically incremented 1 to ... whatever. Using copy/paste or
the duplicate function in Moray will keep the rest of the name (other than the final numeral)
exactly identical, so you won't have to worry about not getting the name right, and 
accidentally creating a new sweep.

HOWEVER, please note, that while these spheres will be CALLED _1, _2, _3, etc, the numerals
themselves do NOT control what order the sphere sweep control points will go in. This is
controlled by the order in which sweepconvert finds them in your source POV file. This is easy
to predict: Moray always exports objects top to bottom in the order they appear in the object
browser tab. And a nice benefit of putting your spheres into a union after you've created them
is that you can add them to the union in any order of your choosing. This order will then 
affect what order they export in as well. This in turn allows you to control the order in
which the control points will be converted.

THE RADIUS OF THE CONTROL POINT

In addition to translating the sphere where you want the control point, you can use Moray
scaling on the sphere to choose the radius of the resulting control point. Uniform scaling is
recommended, because there's no such thing as an unevenly scaled sphere sweep control point,
but if you have uneven scaling, sweepconvert will average the x, y, and z components to 
produce a radius value. 


BOUNDING BOXES

My first hand experience at the time of this writing is that the auto-bounding on sphere
sweeps is HORRIBLE! I used min_extent and max_extent to check out one of my sweeps and found
a rediculously exaggerated bounding box that went to absurdly unnecessary extremes. I have
found, pretty much with no exceptions that it is much more efficient to select a good manual
bounding and then turn Remove Bounds off when rendering. If you want to save your sanity, 
observe this rule when using sphere_sweeps in your image. At least until such time as someone
improves auto-bounding on sphere_sweeps.

Since this is such a hard and fast rule, sweepconvert supports the creation of manual bounds
right in the Moray file. Simple create a box and scale it until it complete envelops where
your sweep should pass (be judicious here... your sweep will get "clipped" by the box if you
guess wrong). Name this box similarly to the following...

      SweepA_bound

That is, the name of the sweep it's a bounding box for, followed by "_bound". Now for the sake
of neatness, put it in the union along with your control points. Make sure the name matches
the sweep name exactly, of course, or sweepconvert won't know what sweep you're bounding, but
that's all there is to it. The bounding shape will get converted to a bounded_by in the
INC file sweepconvert makes for you. 


THE EXPORT/CONVERT/RENDER CYCLE

Now export the file, run sweepconvert with a command line like the following...

   perl sweepconvert.pl sweeps.pov

sweepconvert.pl will be run on the file sweeps.pov, and the result will be output as two
files:

  sweeps_sw.inc
  sweeps_sw.udo

The INC file contains the POV #declared versions of the sweep, and the UDO can be imported
back into a Moray scene file to test out your new creation. Note that by itself the sweep
has no texture. You'll have to assign one in Moray before you can see it <g>. 

From this point on, it's just a matter of going through the usual modeller's hack: model,
export, (convert), render... repeat until you've got what you wanted! 

Happy sweeping. 


---

Disclaimer:
Sweepconvert 0.9 may be freely shared and used by all users of POV-Ray and
Moray as long as the original unmodified script and this document are included.
Sweepconvert is provided "as is" with no explicit or implied warranty of usefulness
or promises of support. 