CTDS [Connect The Dots System] Version 3.0.
A raytracing utility supporting POVRay,
Vivid, and PolyRay. New features include
POVRay 2.0 syntax compatibility;
stronger support for Vivid & Polyray;
grouped primitive output; preprocessing
of input data for variable-replacements;
verbose output; and enhanced object
stats. CTDS continues to be:
FREEWARE by Truman Brown.

Connect The Dots System

[CTDS]

version 3.0

Copyright (c) 1991, 1992, 1993, 1994

Truman Brown

All Rights Reserved

March 6, 1994





























Program Description:

If you are not familiar with the following terms, this
program will probably be of no use to you:
- Raytracing
- Primitives
- Right/left handed coordinate system
- Instance
- Extents
- Quadrics
- Origin
- POVRAY
- VIVID
- POLYRAY

Connect The Dots System [CTDS] Version 3.0 is a unique
program designed to make the development of connected
raytracing objects an easy process. Given a series of
coordinate and radius values, CTDS produces a neatly
formatted raytracing data file composed of spheres
(representing the coordinate points) and cones that smoothly
connect the spheres. This data file can be immediately
incorporated into your raytracing scene.

CTDS supports the syntax of three raytracing programs: The
Persistence of Vision Raytracer (copyright POVTeam), the
VIVID raytracer (copyright Stephen Coy), and the POLYRAY
raytracer (copyright Alexander Enzmann). For information
about any of these programs, or about the art of raytracing
itself, I recommend you visit the Graphics Developers Forum
on CompuServe (GO GRAPHDEV).

CTDS is written in portable ANSI C. Compiled versions are
available for IBM-compatible and Macintosh systems. CTDS is
a standalone utility and requires minimal memory.

In the spirit of POVRAY, CTDS is freeware. However, if you
feel so inclined, the author accepts any and all tokens of
compensation. Please see the copyright notice for
addressing information.


What's New in 3.0:

- The official name of CTDS is now "Connect The Dots System."

- 90% of the program has been rewritten from scratch.

- CTDS now supports POVRAY 2.0 syntax.

- Fuller support for VIVID and POLYRAY has been incorporated.
Except for options which are specific to quadric data, most
command-line parameters are now applicable to all three
raytracers.

- Object naming has been enhanced. Specifying a name on the
command-line will create a defined/declared object with the
desired name. If no name is specified, CTDS will simply write
out an instance of the resulting object.

- Sphere and cone primitives can now be grouped for easier
manipulation.

- Textures can now be specified for just the spheres, just the
cones, or for the entire object.

- Two output formats are now supported: standard and verbose.
Standard format translates the input data into a concise,
optimal description of primitives. Verbose format translates
the input data into specific transformations, allowing further
manipulation of the data.

- Input data is now pre-scanned to perform variable-replacement
of common values. Command-line switches are available to
disable this feature for individual coordinate-components or
for all components.

- Stronger error-checking is now performed for file i/o,
potential degenerate cones, and command-line conflicts.

- The /sc option now supplies information that will allow you to
center objects about the origin if desired.

- The "cylindrical cones only" ("/c1") and "bounds only"
("/bo") options are no longer supported.

- The "Quiet" option works correctly now. Previous versions
tended to leak processing messages to the screen.

- The IBM-compatible version now has a flashier color
interface.


Overview:

CTDS is a utility that does one thing, and does it well. It
connects coordinates smoothly. CTDS does this by reading a
handwritten or utility-generated ASCII file containing
value-sets representing xyz coordinates and a radius value.
CTDS analyses this information and returns a file containing
spheres representing the xyz coordinates and cones that
smoothly connect the spheres.

Sphere primitives of similar radii are connected by cones
attached to the centers of the spheres. Spheres of
differing radii are connected by cones attached at the
common tangent of the spheres. This seamless connecting
methodology is what makes CTDS such a useful (and unique)
tool. Complex arrangements of coordinates can be quickly
and easily connected, enabling the raytrace artist to
design difficult objects with minimal mental excertion.

CTDS provides two primary methods of processing:
- Standard Processing -- the coordinates are processed
sequentially with each subsequent coordinate connected
to the prior coordinate.
- Multi-processing -- the coordinates are processed as
sets. Coordinate groups are identified by blank lines
separating the groups. Each coordinate group is
processed as a unique object.

CTDS data files can be immediately incorporated into a
developing raytrace scene. CTDS can create declared/defined
objects that can be reused, or it can create a single
instance of an object. All object data is neatly formatted
with clear indentation to make editing as easy as possible.


Creating An Input File:

CTDS processes standard ASCII files. You may use your
favorite text editor or word processor to create the input
file. There are also several freeware and shareware
modeling utilities available which create CTDS-compatible
output (i.e., Spiral, Worm, SphereCal).

The CTDS file format is described below:

CTDS works with values representing the 3-dimensional
coordinates of a point in space, and a value representing
the radius of a sphere at that position.

The specific format is:
; X-value Y-value Z-value R-value

> signifies a comment line
> defines X coordinate
> defines Y coordinate
> defines Z coordinate
> defines radius

Example:
; This is a comment line:
; X Y Z R
1.0 1.0 -3.0 1.34
2.0 2.0 3.0 1.34
3.3 1.0 4.5 2.44

As of CTDS Version 2.3, variables and/or simple equations
are allowed to replace numeric values.

Variables must be defined prior to use in an expression. There
are 26 variables available: the letters A thru Z. All variables
must be in written in uppercase.

If coordinate values are to be described as mathematic expressions,
they must be separated by commas. Mathematic functions supported
include addition (+), subtraction (-), multiplication (*),
division (/), modulus division (%), integer exponentiation (^), and
assignments (=). Operator precedence, ranked from highest to
lowest is as follows: ^, *, /, %, +, -, =. Expressions wrapped in
parentheses are given highest precedence of evaluation.

Example:
X = 1 ; declare the variables
Y = 2
Z = 3
R = .5
C = 10

X, Y, Z, R ; Use them.
(X+C), (Y+C), (Z+C), R * C / 2 ; Be sure you have commas separating
10, Y, Z%4, R ; each coordinate component

Blank Lines:

By adding blank lines between groups of coordinate-
sets, you can (1) create multiple individual objects,
and/or (2) perform nested-bounding (this is primarily
applicable to POVRAY). By default, CTDS will process
coordinate sets sequentially, adding connecting cones
between every set of coordinates. The standard output
sequence is:
sphere ...
cone...
sphere...

If the "/m" parameter is specified and a blank line is
encountered, the output sequence becomes:

[ 1st coordinate group up to blank line ]
sphere ...
cone ...
sphere

[ subsequent coordinate groups ]
sphere ...
cone ...
sphere ...

Note that there is no connecting cone between the final
sphere of one coordinate group and the initial sphere
of the next group. This allows each group to be a
completely autonomous object.

If either the "/b", "/bs", or "/bv" parameter is
specified and a blank line is encountered, a bounding
primitive is written at the end of each output
sequence. Individual coordinate groups are bounded,
and then the entire object is bounded.

Warnings, notes, and reminders:
- Only one set of coordinates is allowed per line.
- Each coordinate/radius value-set must be declared on a
single line.
- Input files must contain at least two sets of
coordinates.
- Unless the "/m" command-line option is selected,
sequences of duplicate values are not allowed. This
means that no line may repeat the coordinates of the
prior line.
- 26 variables are available for variable usage (A-Z).
- Variables must be uppercase.
- If you use variables, you must separate the XYZ and
radius components with commas (i.e., "A, B+C, 5.5, D").
- Arithmetic functions supported include: +, -, *, /, %,
^, =, and parentheses.
- Although reasonable error-checking is performed on
incoming data, it is not extensive. So be sure your
input file contains valid data.


Running CTDS:

CTDS is a command-line utility. Syntax and parameter
options are as follows:

Syntax:

CTDS [various optional parameters]
If no parameters are specified, CTDS will display a
short help screen referring you back to this documentation.

Parameters may be prefaced with either a forward-slash
symbol ("/"), a dash ("-"), or a space. All parameters
must be separated by at least one space.

Parameters:

i [inputfilename] Example: /i myfile.ctd
The name of the ASCII input file to
be processed.

o [outputfilename] Example: /o myfile.inc
The name of the ASCII output file
to create.

v Toggle for VIVID-compatible output.
CTDS defaults to POVRAY-compatible
output.

p Toggle for POLYRAY-compatible
output.

# A numeric value specifying the
degree of numeric precision desired
in the output. For instance, a
value of "3" would create output
with three decimal-place precision.
The default precision is six
decimal places.

m Toggle to process coordinate groups
separated by blank lines as
individual objects.

c Toggle to connect the first and
last coordinates of the input file.
This parameter does not work when
the "/m" parameter is also
specified.

so Toggle to only write the data
required to render spheres.

co Toggle to only write the data
required to render cones. Opposite
of "/so."

sv Toggle to write sphere data in the
following verbose format:
- define the sphere at the
origin
- scale it to the correct size
- apply any textures
- translate it to its final
location.

sv1 Toggle to write sphere data in the
following verbose format:
- define the sphere at the
origin
- scale it to the correct size
- apply any textures
- translate it on the x-axis to
a computed value for
subsequent rotations
- rotate it on the z-axis (left-
handed coordinate system)
- rotate it on the y-axis (left-
handed coordinate system)

sv2 Toggle to write sphere data in the
following verbose format:
- define the sphere at the
origin
- scale it to the correct size
- apply any textures
- translate it on the x-axis to
a computed value for
subsequent rotations
- translate it on the y-axis to
its y-coordinate value (left-
handed coordinate system)
- rotate it on the y-axis to
it's z-coordinate

cv Toggle to write cone data in the
following verbose format:
- define the base at the origin
- define the apex at the x-value
of its length
- rotate the cone on the z-axis
- rotate the cone on the y-axis
- translate it to the correct
position relative to the 1st
sphere.

g Toggle to group sphere and cone
primitives separately in output.

b For POVRAY and POLYRAY:
Toggle to perform bounding of
coordinate groups separated by
a blank line.

bs For POVRAY: Toggle to use spheres
for bounding primitives. The
default bounding primitive is a
box.

bv For POVRAY: Toggle to write
bounding primitives in verbose
format.

f # Example: /f 10
For POVRAY and POLYRAY: a numeric value
specifying the "fudge" percentage
to add to bounding primitives. In
the example above, the bounding
primivite will be increased in size
by 10%.

b / bs /bv For VIVID and POLYRAY: Toggle to
write summary of maximum and
minimum extents of coordinate
groups separated by blank lines.
This summary is automatically
written for POVRAY.

d Toggle to disable the writing of
various CTDS variables. Useful if
you are creating several files that
will be used concurrently.

qs For POVRAY: toggle to write quadric
spheres instead of standard
(optimized) spheres.

qc For POVRAY: toggle to write quadric
cones instead of standard
(optimized) cones.

n [objectname] Example: /n MyObject
Specifies name assigned to the
processed object. If no name is
specified, CTDS will simply write
out an instance of the object.

st [texture name]
ts [texture name] Example: /ts SphereTexture
Specifies name of texture to be
applied to spheres.

ct [texture name]
tc [texture name] Example: /tc ConeTexture
Specifies name of texture to be
applied to cones.

tu [texture name] Example: /tu UnionTexture
Specifies name of texture to be
applied to the entire object.
Note: "/tu" may not be used if
either the "/ts" or "/tc"
parameters are also specified.

vxx Disables variable-replacement of x-
coordinates.

vxy Disables variable-replacement of y-
coordinates.

vxz Disables variable-replacement of z-
coordinates.

vxr Disables variable-replacement of
radius values.

vxa Disables variable-replacement of
all coordinates.

qt Toggles "quiet" mode. When active,
prevents CTDS from sending output
to the screen. Useful for other
applications that want to call CTDS
silently.

sc Toggle to add a block of
predeclared transformations to each
individual primitive. This is
useful for scaling textures
separately from the object it is to
be applied to. Note: Not supported
for VIVID output.

Examples:

CTDS imyfile.ctd omyfile.inc
Create a POVRAY output file with the standard
sequence of sphere-cone=sphere-cone=sphere.

CTDS imyfile.ctd omyfile.inc c
Create a POVRAY output file with the standard
sequence, ending with a connecting cone between
the first and last coordinates.

CTDS imyfile.ctd omyfile.vo v
Create a VIVID output file.

CTDS imyfile.ctd omyfile.pi p
Create a POLYRAY output file.

CTDS imyfile.ctd omyfile.inc g b
Create a POVRAY output file with spheres and cones
grouped separately and bounded by boxes.

CTDS imyfile.ctd omyfile.inc tsSTEXT qs
Create a POVRAY output file with quadric spheres
and standard cones. Spheres are assigned a
texture called STEXT.

Warnings and notes:

- Texture names are not predefined. If you specify a
texture with the /tu, /ts (st), or /tc (ct) parameters,
you must define the actual texture yourself.

- The "quiet" mode is only quiet if processing is error-
free. All errors are echoed to the screen.

- Several parameters are not allowed to be specified
together. Examples include /g and /so, /g and /co, and
/ts and /tu. You will receive an error message if your
parameter choices conflict. Error messages are also
generated if options are selected that are not
applicable to the particular raytracing output format
you've selected.

- Verbose sphere/cone formats are useful for capturing
textures at the origin and translating them to the
position of the sphere. The /sv2 format is
particularly useful for "spinning" the sphere about the
origin. If you specify the /qs parameter, CTDS
predefines a primitive called "Dot." You can change
this primitive into anything you want, and have that
object spun about the origin.

- Common values are replaced by the following variable
names:
common x-coordinates - XX
common y-coordinates - YY
common z-coordinates - ZZ
common radii - RR

- VIVID output is automatically formatted for the right-
handed coordinate system (y is z, and z is y).

- For POVRAY and POLYRAY: All CTDS-generated objects have
a commented "dummy subtexture" attached. This may or
may not be of some use.




Manifest

Files included in the package:
CTDS300.EXE The program
CTDS300.DOC The documentation
WHATS.NEW Changes/additions for new version
CTDS.CTD Sample CTDS input file
POVRAY.CTD Sample CTDS input file
VIVID.CTD Sample CTDS input file
POLYRAY.CTD Sample CTDS input file


History:
03/06/94: CTDS v3.0
- Fixed all errors reported by beta testers

01/15/94: CTDS v3.0a
Not publicly released
- Rewrote most of the source code from scratch.
- Added flashy color interface for IBM systems
- Added verbose spheres and cones (/cv /sv /sv1 /sv2)
- Added verbose bounding format (/bv)
- Enhanced VIVID and POLYRAY options and output
- Enhanced file i/o error-checking
- POLYRAY parameter is now /p instead of /x
- Quadric spheres and cones now specified by /qs and /qc
- Added primitive grouping (/g)
- Made specification of object name the determinate of
whether or not an object is declared/defined
- Added variable replacement of common values
- Added exclusions for variable replacements
- Added options summary to output file
- Cleaned up "quiet" mode
- Enhanced output format cleanliness
- Added texture declarations for spheres and cones (/ts
/tc)
- Formalized documentation

07/11/93: CTDS v2.3
- Weakened the integrity parser for the input files.
CTDS now only checks to see if there are valid numbers
in the input file; double sequencing, extraneous data,
etc. are totally ignored -- if there are any errors in
the input file, its up to the user to find them.
- Cleaned up various output functions
- CTDS can now read numbers in the ###e## format.
- Replaced the "# dots connected" display with a
whirly-thingy.
- Added a recursive descent parser, so now variables and
equations can be used in the input file. Variables
available: uppercase A-Z. Arithmetic functions
supported: addition, subtraction, multiplication,
division, modulo, and exponents. Parentheses are also
supported.

01/22/93: CTDS v2.2
- Changed /x to /pr[#] for POLYRAY output
- Added /bo to output bounds only. Writes object extents
for POLYRAY and VIVID.
- Rewrote main processing function of program for easier
maintenance.
- Changed default bounding primitive from spheres to
boxes.
- Added /bs parameter to allow bounding by spheres.
- Rewrote commandline parser for easier maintenance
- Changed /t parameter (connectors only) to /co
- Changed /p parameter (spheres only) to /so
- Added /t option for a named texture
- Shuffled various functions around, deleted a few,
optimized a few
- Fixed a big bounding bug. Minimum values for bounding
weren't working right. Now they are.
- Minor rewrite of documentation.

12/20/92: CTDS v2.0c Macintosh port [Eduard Schwan]
- Changed YourTexture to CTDS_Texture
- Changed YourTransform to CTDS_Transform

??/??/92: CTDS v2.0d
- Fixed bug in declaration of roughness for POV-Ray
declaration.

05/09/92: CTDS v2.0c
- Added /SC parameter to perform scaling of composite
prior to application of texture.
- Translations use declared variables transx1 transx2
transy1 transy2
transz1 transz2
Scalers use declared variables scalex1
scaley1
scalez1


05/02/92: CTDS v2.0b
Fixed a major bug - dot sequences flowing from small dot to
large dot were not being connected properly

04/12/92: CTDS v2.0
Major code rewrite:
- cleaned up source logic; cleared out a lot extraneous
nonsense
- removed DKB Raytracer output option -- outdated
- fixed bug in generating null composites
- added /b parameter; made bounding stats optional
- added /c1 parameter; force usage of cylindrical
connector only
- changed default fudge factor to 0 percent instead of 10
- changed default filenames to CTDS.CTD and CTDS.POV
- Jumped to v2.0
- Removed examples from documentation that were
confusing.
- Resubmitted source to PoV-team for inclusion in PoV 1.0
utilities.

04/12/92: CTDS v2.0a[ddon]
- POLYRAY output added by Alexander Enzmann.

02/15/92: CTDS v1.17a
- Cleaned up spheres-only output.

Not publicly released.

01/21/92: CTDS v1.17
- Made PoV 1.0 syntax-compliant.
- Submitted source to PoV-team for inclusion in PoV 1.0
utilities.

01/16/92: CTDS v1.16
- Added VIVID support.
- Added option to generate connectors only.
- Made command line more flexible (major rewrite of
parser).
- Changed default filenames to VALS.COR and SMOOTH.INC.
- Minor bug fix in /c parameter.

12/22/91: CTDS v1.15
- Removed option to choose whether to use CLIPPED_BYs or
INTERSECTIONS.
- Added option to generate spheres only.
Not publicly released.

11/15/91: CTDS v1.14
- Added option to choose whether to use CLIPPED_BYs or
INTERSECTIONS.
Not publicly released.

- 09/19/91: CTDS v1.13
Modified to default to POV-Ray compatibility. Uses
CLIPPED_BYs instead of INTERSECTIONs for faster
renderings. DKB output still uses INTERSECTIONS.
- Added error message when /m and /c parameters are used
together.
- Revoked shareware constraint, now an official POV-Ray
utility.

08/24/91: CTDS v1.12
- Added whitespace flexibility in commandline.
Not publicly released.

07/30/91: CTDS v1.11
- Minor bug fixes.
Not publicly released.

06/30/91: CTDS v1.10
- CTDS now generates mini-objects and a final composite
instead of UNIONs.
- CTDS automatically bounds the mini-objects and
composite.
- Added additional optional command line parameters:
- /m: multiple autonomous mini-objects
- /d: do NOT generate initial dot and connector
declarations
- /s: use spheres not quadricS
- /n: user defined objectname
- /f#: fudge factor for bounds
- Rewrite of documentation
Minor bug fixes.

06/14/91: CTDS v1.10beta
- Not publicly released.

05/20/91: CTDS v1.00
- ! 1st Official release

05/01/91: CTDS b0.90
- Added command line option for user-specified input and
output files.

04/14/91: CTDS b0.70a
- Algorithm modified to work with DKB 2.10.
- Corrected error in Z axis rotation that resulted in
"divide by zero" error.

04/01/91: CTDS b0.70
- Tangent compensations implemented.
- All axis rotations fully functioning.
- SPIRAL (c) value generator written to test results.

03/25/91: CTDS b0.60
- SMOOTHER renamed to CTDS.
- Full screen interface replaced by command line
implementation.
- DKB rotations recognized as reversed from
documentation.
- Tangent compensation algorithm developed with
assistance from Jim Castro.

03/02/91: SMOOTHER b0.50
- Hard disk crash! No backups. Preliminary test
versions lost.

01/15/91: SMOOTHER b?.??
- The idea is born. Math research begun.


Credits:

Many thanks to:

My wife Madrid for her patience and love. Obsessed
programmers / trace-aholics can be miserable to live with.

My kids Jamaica, Martinique, and Savannah for letting Daddy
hog the PC.

Jim Castro, Math Specialist of California State University,
Northridge for his assistance with the basic geometric
algorithm.

Alexander Enzmann for implementing POLYRAY support.

Eduard Schwan and Jim Nitchals for porting CTDS to the
Macintosh.

All of my beta testers: Aaron Brailsford, Alexander Enzmann,
Dan Farmer, Will King, Mahmut Kursun, David Mason, Mike Miller,
and Heinz Schuller.

All of the raytracing enthusiasts who have used CTDS and given
it the recognition it has today. Thanks!


COPYRIGHT STATEMENT:

Connect The Dots System (CTDS) is protected by United States
copyright laws and international treaty provisions. Full
ownership rights are the exclusive property of the author:

Truman Brown
575 East Howard Street
Pasadena, CA 91104

The author retains full copyright to the program, but authorizes
FREE distribution by electronic bulletin boards (BBS'es), networks,
etc.

Under no circumstances may CTDS be published without the EXPRESS
written consent of the author. This includes CDROM publications
and all forms of printed publications.

Under no circumstances may CTDS be included as part of any
commercial software or hardware package without the explicit
consent of the author.

The author disclaims all guarantees and warranties with respect
to this software, either express or implied, including but not
limited to implied warranties of mechantablility, fitness for a
particular purpose and noninfringement of third party rights.
The author further claims no responsibility for any damages or
losses incurred through use of this program.

Interested parties may contact the author via CompuServe ID
[71477,221].