Otherware/Otherware_1_SB_Development.iso/amiga/misc/3dplot.lzh/3DPlot2.doc

Text File | 1990-12-31 | 14.5 KB | 393 lines

--------------  INSTRUCTIONS FOR 3DPlot v2.0  --------------


------------ INTRODUCTION ------------

3DPlot v2.0 is copyright 1988,1990 by Randy Finch

3DPlot may be freely distributed as long as the this
documentation is distributed with the program.  This program
cannot be sold without the permission of Randy Finch.

If you would like to help support further development of this
program, please send your money, praises and suggestions to:

      Randy Finch
      122 West Oak Hill Dr.          Day: 205-386-2197
      Florence, AL  35630            Evening: 205-767-3528

If you send $10 or more, I will register you to receive the next
release of 3DPlot for free.  If you send $30 or more, I will also
send you the C source code to the program.  Thanks for any
support you can offer, including any bug reports and helpful
hints about additional features.  My BIX handle is rfinch.

----------------- ABOUT THE PROGRAM -----------------

3DPlot allows the user to plot a 3D function of the type
Z=F(X,Y).  The user has control over rotation, scaling, position,
screen resolution, colors, etc.  The program is controlled
through an input window and pull-down menus.  The inputs are
fairly easy to understand but I will present a brief explanation
for each item below.  PLEASE NOTE - The program does not have
very extensive error checking, so it is possible to crash the
program.  I plan to add more error checking in a future release.
Also, there are still a few debugging items in the code, so don't
be alarmed if something unusual happens.  I do believe that the
program is useful and fun in its current state.

3DPlot makes use of several freely distributable shared
libraries.  These consist of:

    arp.library        (for the file requester)
    color.library        (for the color requester)
    iff.library        (for reading IFF files)
    ilbm.library        (for writing IFF files)

These libraries should be included with 3DPlot.  If they are not,
you can contact me for copies or download them from a bulletin
board (BIX has all of them available).  These libraries should be
copied to your libs: directory.

Also, 3DPlot uses the shared math libraries that come with the
Workbench disk.  These libraries will automatically use a math
coprocessor if it is available.  Make sure these libraries are in
your libs: directory.

---------------- THE INPUT WINDOW ----------------

When the program is loaded (either through CLI or Workbench), the
input window will appear.  This window is on the Settings screen
and contains many string gadgets for input from the user.  These
gadgets are divided in a logical manner using boxes.

EQUATIONS

The top box is the EQUATIONS box.  The equation for Z can be
input in the 'Z=' gadget near the top.  The function should be
entered in a standard programming manner as follows:

  Z= 15.4*sin(x/y)-cos(x+y)+2.3e-2

The following operators are supported:

  +         Addition
  -         Subtraction
  *         Multiplication
  /         Division
  ^         Power

and the following functions are supported:

  sin       Sine
  cos       Cosine
  tan       Tangent
  exp       Exponential
  sqrt      Square root
  ln        Natural log
  log       Log base 10
  asin      Arcsine
  acos      Arccosine
  atan      Arctangent
  sinh      Hyperbolic sine
  cosh      Hyperbolic cosine
  tanh      Hyperbolic tangent

The standard hierarchy of operators prevails.

Once the equation is entered, its syntax is checked.  If there
are any errors in the equation, and error message will appear
after the words Error Message: above the gadget.  Also, the 'Z='
gadget will be reactivated with the cursor in the location the
error was detected. You can then proceed to correct the equation.
Once a correct equation is entered, the Error Message will be
Acceptable and the cursor will be activated in the next gadget in
the list (in this case, the Z rotation).

There are gadgets for additional equations but these are not
implemented in this version.

ROTATION

The rotation can be set, in degrees, about each axis.  The
standard mathematics convention is used.  If you are viewing
along the positive Z axis towards the negative Z axis, then a
positive rotation is counter-clockwise, negative is clockwise.
This also holds true for the other axes.  The final orientation
of the plot is dependent on the order of axes rotations.  You can
select one of the axes letters to the left of the three gadgets
by clicking the left mouse button on the letter and the order of
rotation will be changed.  There are six different orders, they
will be cycled through as you continue to click. The rotations
will be applied to the default orientation which is X- positive
to the right, Y-positive upwards, and Z-positive perpendicular to
the screen, pointed towards the user.

NOTE - There is a known bug in these gadgets that causes the
gadgets to sometimes not push the contents to the undo buffer.
Also, if you click in a gadget and then not press return, a wrong
angle may result.

ORIGIN

This is simply the X and Y screen coordinates for the origin of
the plot.

SIZING

Proj Plane is the position along the default Z-axis where the
projection plane is located.

View Dist is the distance of the viewer from the projection
plane.  In this version, the distance only affects perspective,
not the size of the plot.  Scale can be used to resize.

Proj Plane and View Dist are in plotting units, not pixels.

Scale is the number of screen pixels per plotting unit.  This
value can be used to control the size of the plot.  This value
will have to be changed when the screen resolution is changed in
order to maintain a constant plot size.

LINE SPACING

The 3D plot will consist of contour lines at constant values of
X, Y, or both.  These values set the spacing, in plot units,
between these lines.

PLOT SPAN

These values determine the plotting range in coordinate units
along the X and Y axes.  The plotting range along the Z-axis is
determined by the equation being plotted.

PLOT PRECISION

When contour lines are being drawn at constant values of X and Y,
the distance between the calculated points along the lines is
determined by these numbers (in plot units).  The smaller these
numbers are, the more detail that is available for plots that
vary widely over short distances.  A line is drawn between each
calculated point.  These values only apply to the Normal plot
(see below).

AXES SPAN

This is identical to the Plot Span except it applies to the axes.
By having the axes span separate, the axes can be made to extend
beyond the range of the plot.  Note that a Z-range must be given.

AXES PRECISION

This is the same as Plot Precision except it applies to the axes.
The axes are drawn as dots at each calculated point rather than
lines connecting the points.  This prevents the axis lines from
ever overwriting a contour line that is in front of the axis.  If
this number is too large, the axes will be dotted lines.

SURFACE

Surface is a boolean gadget that cycles through three choices as
the user selects it.  The options are 'X and Y', 'X only', and 'Y
only'. These options control how the contour lines are drawn.  If
'X and Y' is selected then contour lines will be drawn along both
axes.  'X only' restricts the plot to contour lines at constant
values of Y, and 'Y only' restricts the plot to contour lines at
constant values of X. These options only apply to the Normal plot
(see below).

AXES TYPE

Axes Type is another boolean gadget that cycles through three
different options for the type of axes to be drawn.  The 'None'
option results in no axes being drawn.  The 'Star' option results
in standard axes being drawn with each axis crossing the other
two at the origin.  The 'Box' option results in a rectangular
box being drawn with the vertices equal to the Axes Span values.

NOTE

This gadget allows the user to store a comment about the plot.

------------ PROJECT MENU ------------

This menu contains nine items.  Some of these are not yet
implemented. The >> symbol to the left of some menu items
indicates that these items have subitems.

NEW

This item is used to reset all plotting parameters to the program
defaults.

OPEN

This item allows the retrieval of stored files.  It has three
subitems: All, Settings, and Picture.  Settings will retrieve
only the settings displayed on the input window (file must have
an extension of .3DPL, see Save As option below), Picture
retrieves IFF ILBM graphics files, and All gets both.  If the
ILBM file is named MyPic, then the settings file should be named
MyPic.3DPL.  When choosing a settings file only, a picture file
only, or both, you can select either the picture or the settings
file.  The program will adjust the name appropriately.

When choosing Open, the ARP file requester (from arp.library,
thanks Charlie Heath and others!) appears.  It lists files and
directories in a selection area.  The list can be scanned up or
down by using the arrows or proportional gadget on the right side
of the file selection area.  A directory can be chosen by
clicking on the directory name or typing it in the Drawer gadget.
A file can be selected by clicking on the name or typing it in
the File gadget.

Once a file is selected, it can be loaded by clicking on the OK
gadget, or it can be cancelled by clicking on Cancel.

SAVE

This item allows the Settings, Picture, or All to be saved under
the previously selected filename.  The picture is saved as an IFF
ILBM graphics file that can be retrieved by Deluxe Paint and
other graphics packages.

SAVE AS

This item works just like save except a requester identical to
the Load requester is displayed so a new filename can be
selected.  The picture is saved as an IFF ILBM graphics file that
can be retrieved by Deluxe Paint and other graphics packages.
The settings file is saved as an IFF 3DPL file (my own creation).
When you save files, the program will insure that the settings
file is identical in name to the picture file except with a .3DPL
extension.

COLOR

This item has three subitems: Adjust, Load, and Save.

Adjust displays a color requester on the Graph screen that allows
the colors to be changed by the user.  This requester was written
by the Dissidents and is implemented in color.library.

The requester is similar to others you have seen.  A set of RGB
sliders appear along the right.  These can be changed to a set of
HSL sliders by selecting one of the letters in RGB.  The color
palette appears at the top and is arranged top to bottom, left
to right.  The current color has a box around it.  3DPlot uses
color 0 (upper left of color palette) for the background.  Color
1 is the border color.  Color 2 is the axes color.  Color 3 will
be used for text, but is not used in this version.  In low
resolution, colors 4-27 (24 colors) are used for the graph (more
about this later).  Colors 28-31 are not currently used.  In high
resolution, colors 4-15 (12 colors) are used for the graph.

You can copy one color to another by choosing the color to be
copied, choosing the Copy gadget, and then selecting the color to
be copied to.

You can smoothly range a series of colors by choosing the first
color, then the Spread gadget, and finally the second color.

You can undo the last change you made with the Undo gadget.

The Default gadget is not implemented in this version.

The Load and Save menu subitems can be used to load and save
color palettes.  When you save a palette, it is stored as an ILBM
file with only color information.  When loading a palette, you
can load one of these shortened file or you can load the color
palette from a complete ILBM file.

SCREEN

This item can be used to choose the screen resolution you wish to
work with.  Options are low- and high-resolution, interlaced and
non- interlaced, and normal, medium overscan, and severe
overscan.  The overscan screens are not yet implemented.

TITLE

This item simply toggles the title bar of the graph screen on and
off.

PRINT

This item will be used to do a graphics dump to the printer but
is not yet implemented.

EXIT!

End the program.  NO WARNING is given.

------------- FUNCTION MENU -------------

The Function menu contains four items.

PLOT

This is the action item.  Choosing one of its subitems makes
3DPlot go to work.  The plot appears on a separate screen, the
Graph screen.  The four plot options are: Normal, Hidden, Solid,
and Contour.  Upon choosing one of these options, 3DPlot will
calculate values of Z at various points within the plot range
specified by the Plot Span gadgets on the input window.  Minimum
and maximum distances from the viewer are determined and then
split into either 24 or 12 equal ranges, depending on the screen
resolution.  Plotting then begins.  (There could be a rather long
delay before a plot begins if a large range and small spacing is
chosen.  It is usually good to start with a rough quick plot and
then do a detailed plot when all looks well.)  Far points will be
plotted in color 4, near points will be plotted in color 27 or 15
depending on the resolution, and points in the middle will be
distributed between the intervening colors.

Normal causes the plot to draw lines along constant X or Y values
or both based on the Surface gadget setting.  The lines are drawn
separately and have a resolution based on the Plot Precision
settings. This plot usually takes the longest.

Hidden draws the graph as a series of hollow (filled with
background color) four-sided polygons starting with the
fartherest corner and working forward.  The size of the polygons
is determined by the Line Spacing gadgets settings.  Since each
successive polygon appears in front of the previously drawn
polygons, the graph will have hidden lines removed.

Solid is exactly the same as Hidden except the four-sided
polygons are filled with the plot color rather than the
background color.  This makes the graph appear as a solid figure.

Contour will draw a flat graph with no perspective, letting the
graph colors define the shape of the graph.

Once the graph is drawn, the axes are drawn unless the Axes Type
is set to None.

STOP PLOT

Choosing this item after choosing a Plot option will interrupt
the plot and return control to the user.  The interuption will
not occur until the currently plotting contour line is complete.

SETTINGS

Selection of this item causes the Settings screen containing the
input window to be brought to the front.

GRAPH

Selection of this item causes the Graph screen containing the
Plot (if one has been plotted) to be brought to the front.

--------- TEXT MENU ---------

This menu contains several items for adding text to the plot
screen. None of these items are implemented yet and are not
discussed.

--------------- CLOSING REMARKS ---------------

I hope you enjoy the program.  If you have any questions, you can
write me or contact me on BIX.