Monster Media 1993 #2/Image.iso/graphics/trans4.zip/TRANS4.DOC

Text File | 1993-07-03 | 23KB | 491 lines

TRANS4.DOC 7/3/93

                           TRANS4 Version 1.1

********************** NOTICE *********************************************

TRANS4 v1.1 is a FREE, copyrighted program.  Feel free to distribute the ZIP
as you see fit.  Keep in mind that there is NO support, and that you use this
product AT YOUR OWN RISK!!!

TRANS4 copyright (c) 1993, Lyn Ratcliff

***************************************************************************


TRANS4 1.1 Quick Reference

What is TRANS4?

TRANS4 is an interactive graphics demonstration program which displays
colorful, animated 4-dimensional wireframe objects on the IBM compatible
personal computer. TRANS4 allows you to choose display characteristics of
these objects, including motion rates and colors.
TRANS4 has a number of figure types which you can modify to your liking,
and the ability to display 4-dimensional figures that you create using
instructions in a standard text file.

SYSTEM REQUIREMENTS:

To use TRANS4, you'll need an IBM AT compatible computer with color VGA
graphics, and a math coprocessor (287 or 387) or fully functioning 486 CPU.
TRANS4 will function on a VGA graphics capable system without a math
coprocessor, but VERY SLOWLY!

An ASCII (plain text) editor is required if you wish to create your own figures.

FILE TYPES:

TRANS4 uses two file types, with the extensions .TR4 or .YF4.  The .TR4 files,
such as DEFAULT.TR4, contain information written by TRANS4 when you save a
color scheme from within TRANS4.  The .YF4 files are examples of figures that
you can create yourself.

RUNNING TRANS4:

Simply type TRANS4 at the DOS prompt in the TRANS4 directory.  This takes you
to the entry screen.  At the top of the screen are instructions for cursor
movement from the keyboard.  Below the instructions is a key of the 16 colors
available to you, labeled from 0 to F.  Immediately below the color key are the
line colors, which may be changed by the use of the arrow keys.  There is a red
marker on the left which indicates which parameter field is currently active
for change.  In the bottom right corner of the screen is a preview of the
figure.  Press the ENTER key to see the full screen display, and then any key
to return to the entry screen.

Now press the PAGE DOWN key to move to the "...projections..." field (the red
indicator will move as well) and use the four arrow keys to change this value.
Note what happens in the corner display!  Okay, change it back to 1 and press
PAGE DOWN again.

The next four fields control the rotation rates in the body-centered axes.  Go
ahead and change these around.

Now page down to the Figure Type field, and use the up or down arrows to scroll
through the various figures. Note that the Hypercube and Octahedra figure types
have color editing capability (in the Line Colors field); feel free to page
back up and change or blank out some or all of them!  The remaining figure
types are randomly generated, so there is no line color editing available for
them.  Press ENTER at any time to see the full screen display.

You can save any changes you make to the Hypercube and Octahedra figures when
you exit TRANS4.  From the entry screen, press ESCAPE and then enter y to the
"save" prompt. Then enter a one to eight character filename, such as MYCOLORS,
then press ENTER. Your parameters will be saved in a file named MYCOLORS.TR4.
To load your file, simply type TRANS4 MYCOLORS.TR4 at the DOS prompt.  There
are a number of sample .TR4 files included with the program.

INTERLUDE:

To get an idea of what TRANS4 can do very easily in an automated demo
mode, from the DOS command line simply type DEMO or TRANS4 DEMOTR4.BAT.

TRANS4 will "play" the file DEMOTR4.BAT as a sequence of timed displays, moving
smoothly from figure to figure (this is best from a hard disk).  Press any key
to skip a display, and press F3 to exit the demo.

MAKE YOUR OWN FIGURES:

You may have noticed some unusual figures as you watched the demo.  These were
loaded from .YF4 files.  To make your own figures, use a text editor to modify
a copy of one of the existing .YF4 files.  Instructions are towards the end of
this document.

BATCH/DEMO MODE:

String your favorite figures together for an eye-catching display!  TRANS4
can be called from within a batch file, one example DEMOTR4.BAT is included
with the distribution disk.  Typing DEMOTR4.BAT will cause this batch file to
run TRANS4 once for every line in the DEMOTR4.BAT file.  This file makes
extensive use of command line options, which are described on the later.

You can create your own sequence of displays and collect them in a .BAT file of
your own choosing, such as MYDEMO.BAT.  Use TRANS4 to play this file as a
continuous loop by the command TRANS4 MYDEMO.BAT.  The filetype MUST be .BAT
with version 1.1.

COMMAND LINE OPTIONS:

For greater control over the motion of figures, TRANS4 accepts instructions
from the command line used to invoke the program.  These commands may be used
to override any of the parameters set in the .TR4 or .YF4 files except for
line colors.  Use command line options to skip entry screens, file saving
screens, or set time limits on displays.  Options consist of the backslash
character / followed by one of the characters in the table below.  For those
options which pass a value to TRANS4, the value should immediately follow the
instruction without spaces inbetween.  (Note: I believe this requirement is no
longer necessary)  Examine the file DEMOTR4.BAT for examples of the use of
command line options.  All distance values are in units of pixel width.  Do
not use commas in your values; i.e. use 1027 rather than 1,027.

Note that the following group consists of mostly lower-case letters.  Use of
upper case letters will be explained after the list.

/a  Skip the parameter entry screen and go directly to the display screen.
    This option is useful when stringing timed displays together with /t in
    demo mode.  Takes no values.

/b  Skip the save screen and exit.  This option is useful  in demo mode.
    Takes no values.

/e  Sets the number of replications to draw before erasing.  Ex.: /e27 will
    draw the figure for 27 rotations before starting to erase the old
    replications.  Values above 200 will be adjusted to 200.

/f  Sets the figure type when loading a .TR4 file.  F=0 for the hypercube, f=1
    for the octahedron, f=2 for potluck, f=3 for odd potluck, and f=4 for
    PotSym 8.

/i  Rotate the figure relative to the rotation axis prior to animation.  For
    instance, /i45/j55 will set the hypercube on a corner so that it spins
    around a diagonal axis. The value passed to TRANS4 is the angle in degrees.

/j,/k,/l  Similar to /i, but for the other three angles.  Order is the same as
    listed in the entry screen.

/m  Sets the distance to which the figure will retreat, relative to the screen.

/n  Sets the distance to which the figure will approach.  TRANS4 will not allow
    values less than 250 minus the viewing distance (see /v below).

/o  Alternate rotation for the 3rd rotation.  The default rotations are:
    rotation in xz plane, then xy, xw, and xz planes, where these planes are
    fixed relative to the body of the figure AFTER the initial rotations
    carried out by the /i,j,k,l options.  The /o option replaces the xw
    rotation by a zw rotation.  Many people prefer to use this option.

/p  Sets the zoom rate.

/t  Sets a timer for dislay.  If /b is specified, TRANS4 ends after time is up;
    otherwise a new figure is generated.  Use this option in demo mode with
    /a/b, or with /f2, 3, or 4 to generate a new figure without leaving
    display mode.  Values are in seconds.

/u  With this option, replications are updated offscreen and displayed only
    after each new replication is finished.  Useful if you intend to pause the
    program and examine or capture the screen.  Speed, resolution,  and sense
    of motion are degraded if this option is set.

/v  Sets the viewing distance from the screen used to calculate perspective.
    The default is 800;  the minimum allowed is 250.  The use of the default
    results in exagerated perspectives, so purists may wish to overide this
    value; this will require an adjustment (down) in /n /m values to maintain
    apparent figure size.  For proper perspective, calculate pixel size:  for
    example, the TRANS4 display is 640 pixels wide; if your VGA display has an
    illumination width of 9 inches, then there are 640/9 or 71 pixels/inch.
    To view a proper perspective from a distance of 20 inches, then 20*71=1420
    is the number to use, i.e. /v1420.  Maximum is 5000.

/w,/x,/y,/z  Overides the angle incrementation rates of rotations.   The
    rotation sequence is described above in the /o option discussion,
    i.e. /w in xz plane for angle phi, /x in xy plane for theta, /y in xw or
    zw plane for eta, and /z in xz plane for psi.

/*  Cycle the diplayed colors.  This will do some peculiar things on some .TR4
    f=0,1 figures, though.

/&  Cycle the pallete after each set of replications defined by /e.

SPICE:

Upper case letters may be used as well.  BUT,

use of E, I-N, P, and W-Z will result in the supplied number being replaced by
a randomly generated number on the interval of 1/2 to 3/2 times the number you
supplied.  This works well with /a/b/t, so that you don't get the same
orientation of the figures every time the figure is displayed with a timer.

ALSO, if you input a negative number, then the use of these capitalized /
options will return a 50/50 chance of a +/- value being returned (actually a
100% chance of a positive or negative number).

/F will randomly select one of the figures.

EXAMPLES:

TRANS4 /A/b/T15/E8/F2/I-60/J-60/K-60/L-60/M700/P27/W-250/X-250/Y-250/Z-250

Type this at the command line, hit return, and you'll see a variety of things.
This is somewhat busy on a 386/7DX40, and frantic on a fast 486.  Raise/lower
the W-Z values if you have a slow/fast computer.

Command line flags may be added when playing a .BAT file as well, overriding
the options used in the .BAT file, i.e.

       TRANS4 play.bat /& /W-800/X-1800/Y-900/Z-300

This will speed things up a bit.

FUNCTION KEYS:

F3     Get out fast.
F4     Toggle which turns the zoom on/off.
F5-8   Toggle for the four rotations, on/off.


CREATING YOUR OWN FIGURES:

To create figures of your own design, you will need a text editor that has
the capability to save plain (ASCII) text files.  Most operating systems come
with such a text editor; see the operating system manuals for details on the
correct usage if you are unfamiliar with your particular editor.  The editor
supplied with DOS 4.0, accessed via the DOSSHELL command, and the Microsoft
Windows 3.0 accessories editor are both suitable for this task.

TRANS4 is able to read text files containing data which may be used to
construct a figure.  Such files are required to conform to a specific format
for TRANS4 to be successful in correctly interpreting the data.  For this
reason, we STRONGLY recommend that all active applications containing data which
could conceivably be lost be terminated before attempting to run an untested
.YF4 file with TRANS4.  For instance, while TRANS4 will run successfully in
the DOS box of Windows or OS/2, it would be prudent to exit Windows or boot to
DOS before testing a new .TR4 file.  No problems, such as system hangs, have
been reported as of yet, but as it is impossible to predict all of the many
types of file formats that might conceivably be fed to the program we can never
claim to have tested TRANS4 under every condition.  (we tried, though!)

There are a couple of instances in which TRANS4 will display something that
you did not expect: if TRANS4 does not find the file you specified on the
command line it will automatically load the default .TR4 file DEFAULT.TR4.
This is usually not too traumatic.  The other instance is when the format of
the .YF4 file is other than expected, in which case TRANS4 may not appear to
respond to the usual keypresses.  Should this happen, exit the program by
pressing the F3 key and examine your .YF4 file.  The usual problem is that
TRANS4 did not find:

        The right number of pieces of data on a line
        The right number of commas (used to separate data) on a line
        more or fewer POINTS defined than specified
        more or fewer LINES defined than specified

TYPICALLY, PRESSING F3 WILL GET YOU OUT OF ANY TROUBLE within the program.

Okay, hope we haven't scared any-one off!

The best way to create a figure is to copy and edit one of the .YF4 files
which came with your distribution diskette.  They also serve as examples.
To copy a file, enter the following at the DOS prompt in the TRANS4 directory:

        COPY HYPRCUBE.YF4 MYFIG.YF4

Then open MYFIG.YF4 with your editor.

The rules for describing a figure are not very complicated.  TRANS4 expects
every line in the file to start with a description, which can be as long or
as short as you wish, but it must be present.  The description is a string of
letters or characters which contain no commas or spaces.  Commas are used to
separate the pieces of data or numbers that are the instructions for TRANS4.
The decription is considered a piece of data (although it is ignored by TRANS4)
and so every description should have a comma after it except for the first
line, which is the name of your figure.

The format of the .YF4 file is as follows:

1st line: The name of your figure

          eg: Buncha???

2nd line: The coordinates that your figure is centered on.

          eg: Coordinates, 0, 0, 0, 0

          These correspond to x, y, z, w values.  TRANS4 uses w to represent
          the location in the fourth dimension of the figure.  Currently,
          TRANS4 does not use all of this information; it is present to
          maintain compatibility with future versions of TRANS4, so you don't
          need to change this line but it must be present.

3rd line: The number of points to which lines will be drawn.

          eg: Number.of.points, 4

          After reading this number, TRANS4 will expect the coordinates for
          these four points, i.e. their x, y, z, w values.  The coordinates
          are listed on separate lines, so in this example TRANS4 expects four
          additional text lines with coordinate values.

4th line: First of the sets of coordinates in the order x, y, z, w.

          eg: First_point 200, 0, 0, 0

          then the remaining coordinates

              Secondpoint 0, -200, 0, 0
              third.of.four 0, 0, 75, 150
              lastpointofall 0, 0, 0, -99

Next(5+): The number of colored lines drawn connecting the points

          eg: Draw.this_manyLines, 4

          Again, once this number is read TRANS4 will expect this many text
          lines to follow with instructions on which points to connect and
          the color of the lines.

Next(6+): First of the Line Instructions

          eg: Line.number.one.connects.point1_to_point2_yellow, 1, 2, 14

              two.three.Blue, 2, 3, 9
              three.four.White, 3, 4, 15
              fourToOneRed, 4, 1, 12

          The three values correspond to 1) the number of the point on which
          the line starts, as determined by the sequence of points as listed
          above, 2) the number of the point to which the line will be drawn
          and 3) the color of the line.

          The color of the line is determined by a number from 0 to 15.  These
          colors are displayed on the entry screen in TRANS4 directly under the
          instructions for cursor movement, and are labeled 0 (Black) to F
          (bright white).  One must use the numerical value which corresponds
          to the letter: A=10, B=11, C=12, D=13, E=14, and F=15.

          0  BLACK       4  RED           8  GRAY             12  LIGHT RED
          1  BLUE        5  MAGENTA       9  LIGHT BLUE       13  LIGHT MAGENTA
          2  GREEN       6  BROWN        10  LIGHT GREEN      14  LIGHT YELLOW
          3  CYAN        7  WHITE        11  LIGHT CYAN       15  BRIGHT WHITE

Next(7+): Number of replications to draw before erasing

          eg: Replications, 12

          This is the number which corresponds to, and can be overridden by,
          the /e command line option.  It appears in the text entry screen,
          and from there can be changed interactively (but not saved).

Next(8+): Incrementation rates for the four angles; phi, theta, eta, psi

          eg: AngleRates, -67, 127, 876, 142

          These are the values that can be overridden by the /w, /x, /y, and
          /z command line options.  They appear in the entry screen as well,
          where they may be modified (but not saved) from the entry screen.

Next(9+): Maximum Distance to which the figure will retreat relative to the
          screen location.  This value is typically positive (greater than
          zero) for instances in which the figure would be "behind" the VGA
          screen, or further away from the viewer than the surface of the
          screen... although technically that direction is defined to be
          in the direction of decreasing (negative) values on the Z axis
          (see discussion on COORDINATE SYSTEM below).  Values are in units
          of pixel-width.  So, if you want the figure to "shrink" as it
          moves to a distance of two feet behind the screen, try

          eg: MaxDistance, 1700

          See the discussion on the /m command line option for more details.

Next(10+): Minimum Distance to which the figure will approach.  This number
           can be negative, corresponding to a distance between the viewer
           and the screen.  The /n command line option overrides this.  As
           noted just above, this corresponds to a POSITIVE z value.

           eg: MinDistance, -500

Next(11+): Zoom Rate.  The larger the number, the faster the zoom rate.
           The /p command line option overrides this value.

           eg: Zoom, 27

Next(12+): Viewing distance (in pixel-widths).  This value is used to determine
           the proper perspective.  Large values will result in little
           perceivable perspective (shrinking of the portion of the figure
           furthest from view) and very small values will result in an
           exagerated perspective.  The absolute minimum TRANS4 will allow is
           250; smaller values will be adjusted upward to 250.  The default is
           800, which slightly exagerates the perspective for most normal
           viewing distances, but aids in providing a discernable depth cue.
           This value may also be overridden with the /v command line option.

           It is included in order to maintain compatibility with future
           versions of TRANS4.

           eg: View_Distance, 800.

Last(13+): Initial angles.  These are angles that the figure is rotated PRIOR
           to being set in motion.  In other words, you can change the
           orientation of an object before it starts spinning.  As an example,
           try both of the following commands from the DOS prompt

                TRANS4 3DEFAULT.TR4 /i0 /j0    /w500 /x0 /y0 /z0
                TRANS4 3DEFAULT.TR4 /i45 /j55  /w500 /x0 /y0 /z0

           In the first instance a cube, initially resting as though on a
           flat surface, will begin to spin on its vertical axis (because
           of the /w500 option).  In the second instance, the cube is rotated
           so that it sits on a corner prior to spinning on the vertical axis.

           eg: InitialAngles, 45, 55, 0, 0

           Values are in degrees.  The /i, /j, /k, and /l command line options
           will override these values.

           NOTE: If the /o command line option is set, it applies to both
           initial rotations and motion.

           This is the last line in the file.


FIGURE SIZES AND OTHER CONSIDERATIONS

As a general rule, figures should be sized so that they fit into a space that
does not exceed 250 or so in any direction (viz. between -250 and 250).  The
screen resolution, or "graininess", will not allow enough detail to be revealed
to justify larger numbers, at least for your first figures.  In order to allow
flexibility, TRANS4 will accept numbers larger in magnitude, but the figure
should NOT be allowed to approach too closely; TRANS4 checks for most instances
that would cause an overload (overflow) and so you should not run into trouble;
if such an instance occurs TRANS4 will kick you out of the program and display
an OVERFLOW message.

Secondly, remember that all rotations will occur around axes which pass through
the origin (0, 0, 0, 0) and so plan accordingly.  Most of the sample .YF4 files
have figures which are centered on the origin; ROCKET.YF4 is an example of a
file with a figure which is not.


USAGE

To load a .YF4 file, type TRANS4 followed by the filename and then any command
line options; then press ENTER.


COORDINATE SYSTEM

The coordinate system is set up such that the screen is the X,Y plane, with
X positive to the right, negative to the left, and Y is positive up.  Z is
positive from the screen to the viewer, and negative behind the screen.  Thus,
the origin (0, 0, 0, 0) is located in the center of the screen.
And W? Good question!


THREE DIMENSIONAL FIGURES

If you wish to construct 3-D figures, simply set the w coordinate values to
zero in the coordinate sets.  Using the command line options /k0 /y0 will
keep the figure from "squashing" by eliminating the rotations into the fourth
dimension.  Of course, you may prefer to see them squashed.  See OCTAHED3.YF4,
for example.


DON'T BE AFRAID!

If you come up with some really great .YF4 files, don't be afraid to share them
with your friends; post them on your friendly neighborhood electronic bulletin
board!  And let us know where all the good collections are...

ENJOY!

******* DONATIONS graciously accepted if sent to the following address & will
*******           be applied toward tools used in the continuing development
*******           of TRANS4 and other nifty, educational electronWares.

Bitzenboltz ElectronWare
RR#1 Box 90
Burbank, SD 57010


***All product names mentioned are the trademarks or registered trademarks of
their manufacturers.