home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 141.lha / 3DPlot.doc < prev    next >
Text File  |  1986-11-21  |  15KB  |  413 lines
  1. --------------------  INSTRUCTIONS FOR 3DPlot v1.0  ------------------
  2.  
  3.  
  4. ------------
  5. INTRODUCTION
  6. ------------
  7.  
  8. 3DPlot is copyright 1988 by Randy Finch
  9.  
  10. 3DPlot may be freely distributed as long as the this documentation is
  11. distributed with the program.  This program cannot be sold without the
  12. permission of Randy Finch.
  13.  
  14. If you would like to help support further development of this program,
  15. please send your money, praises and suggestions to:
  16.  
  17.       Randy Finch
  18.       122 West Oak Hill Dr.          Day: 205-386-2252
  19.       Florence, AL  35630            Evening: 205-767-3528
  20.  
  21. If you send $10 or more, I will register you to receive the next
  22. release of 3DPlot for free.  If you send $30 or more, I will also send
  23. you the C source code to the program.  Thanks for any support you can
  24. offer, including any bug reports and helpful hints about additional
  25. features.  My BIX handle is rfinch.
  26.  
  27.  
  28. -----------------
  29. ABOUT THE PROGRAM
  30. -----------------
  31.  
  32. 3DPlot allows the user to plot a 3D function of the type Z=F(X,Y).  The
  33. user has control over rotation, scaling, position, screen resolution,
  34. colors, etc.  The program is controlled through an input window and
  35. pull-down menus.  The inputs are fairly easy to understand but I will
  36. present a brief explanation for each item below.  PLEASE NOTE - The
  37. program does not have very extensive error checking, so it is possible
  38. to crash the program.  I plan to add more error checking in a future
  39. release.  Also, there are still a few debugging items in the code, so
  40. don't be alarmed if something unusual happens.  I do believe that the
  41. program is useful and fun in its current state.
  42.  
  43.  
  44. ----------------
  45. THE INPUT WINDOW
  46. ----------------
  47.  
  48. When the program is loaded (either through CLI or Workbench), the input
  49. window will appear.  This window is on the Settings screen and contains
  50. many string gadgets for input from the user.  These gadgets are divided
  51. in a logical manner using boxes (gold colored if the standard palette
  52. is used).
  53.  
  54.  
  55. EQUATIONS
  56.  
  57. The top box is the EQUATIONS box.  The equation for Z can be input in
  58. the 'Z=' gadget near the top.  The function should be entered in a
  59. standard programming manner as follows:
  60.  
  61.   Z= 15.4*sin(x/y)-cos(x+y)+2.3e-2
  62.  
  63. The following operators are supported:
  64.  
  65.   +         Addition
  66.   -         Subtraction
  67.   *         Multiplication
  68.   /         Division
  69.   ^         Power
  70.  
  71. and the following functions are supported:
  72.  
  73.   sin       Sine
  74.   cos       Cosine
  75.   tan       Tangent
  76.   exp       Exponential
  77.   sqrt      Square root
  78.   ln        Natural log
  79.   log       Log base 10
  80.   asin      Arcsine
  81.   acos      Arccosine
  82.   atan      Arctangent
  83.   sinh      Hyperbolic sine
  84.   cosh      Hyperbolic cosine
  85.   tanh      Hyperbolic tangent
  86.  
  87. The standard hierarchy of operators prevails.
  88.  
  89. Once the equation is entered, its syntax is checked.  If there are any
  90. errors in the equation, and error message will appear after the words
  91. Error Message: above the gadget.  Also, the 'Z=' gadget will be
  92. reactivated with the cursor in the location the error was detected.
  93. You can then proceed to correct the equation.  Once a correct equation
  94. is entered, the Error Message will be Acceptable and the cursor will be
  95. activated in the next gadget in the list (in this case, the Z
  96. rotation).
  97.  
  98. There are gadgets for additional equations but these are not
  99. implemented in this version.
  100.  
  101.  
  102. ROTATION
  103.  
  104. The rotation can be set, in degrees, about each axis.  The standard
  105. mathematics convention is used.  If you are viewing along the positive
  106. Z axis towards the negative Z axis, then a positive rotation is
  107. counter-clockwise, negative is clockwise.  This also holds true for the
  108. other axes.  The final orientation of the plot is dependent on the
  109. order of axes rotations.  You can select one of the axes letters to the
  110. left of the three gadgets by clicking the left mouse button on the
  111. letter and the order of rotation will be changed.  There are six
  112. different orders, they will be cycled through as you continue to click.
  113. The rotations will be applied to the default orientation which is X-
  114. positive to the right, Y-positive upwards, and Z-positive perpendicular
  115. to the screen, pointed towards the user.
  116.  
  117. NOTE - There is a known bug in these gadgets that causes the gadgets to
  118. sometimes not push the contents to the undo buffer.  Also, if you click
  119. in a gadget and then not press return, a wrong angle may result.
  120.  
  121.  
  122. ORIGIN
  123.  
  124. This is simply the X and Y screen coordinates for the origin of the
  125. plot.
  126.  
  127.  
  128. SIZING
  129.  
  130. Proj Plane is the position along the default Z-axis where the
  131. projection plane is located.
  132.  
  133. View Dist is the distance of the viewer from the projection plane.  In
  134. this version, the distance only affects perspective, not the size of
  135. the plot.  Scale can be used to resize.
  136.  
  137. Proj Plane and View Dist are in plotting units, not pixels.
  138.  
  139. Scale is the number of screen pixels per plotting unit.  This value can
  140. be used to control the size of the plot.  This value will have to be
  141. changed when the screen resolution is changed in order to maintain a
  142. constant plot size.
  143.  
  144.  
  145. LINE SPACING
  146.  
  147. The 3D plot will consist of contour lines at constant values of X, Y,
  148. or both.  These values set the spacing, in plot units, between these
  149. lines.
  150.  
  151.  
  152. PLOT SPAN
  153.  
  154. These values determine the plotting range in coordinate units along the
  155. X and Y axes.  The plotting range along the Z-axis is determined by the
  156. equation being plotted.
  157.  
  158.  
  159. PLOT PRECISION
  160.  
  161. When contour lines are being drawn at constant values of X and Y, the
  162. distance between the calculated points along the lines is determined by
  163. these numbers (in plot units).  The smaller these numbers are, the more
  164. detail that is available for plots that vary widely over short
  165. distances.  A line is drawn between each calculated point.  These values
  166. only apply to the Normal plot (see below).
  167.  
  168.  
  169. AXES SPAN
  170.  
  171. This is identical to the Plot Span except it applies to the axes.  By
  172. having the axes span separate, the axes can be made to extend beyond
  173. the range of the plot.  Note that a Z-range must be given.
  174.  
  175.  
  176. AXES PRECISION
  177.  
  178. This is the same as Plot Precision except it applies to the axes.  The
  179. axes are drawn as dots at each calculated point rather than lines
  180. connecting the points.  This prevents the axis lines from ever
  181. overwriting a contour line that is in front of the axis.  If this
  182. number is too large, the axes will be dotted lines.
  183.  
  184.  
  185. SURFACE
  186.  
  187. Surface is a boolean gadget that cycles through three choices as the
  188. user selects it.  The options are 'X and Y', 'X only', and 'Y only'.
  189. These options control how the contour lines are drawn.  If 'X and Y' is
  190. selected then contour lines will be drawn along both axes.  'X only'
  191. restricts the plot to contour lines at constant values of Y, and 'Y
  192. only' restricts the plot to contour lines at constant values of X.
  193. These options only apply to the Normal plot (see below).
  194.  
  195.  
  196. AXES TYPE
  197.  
  198. Axes Type is another boolean gadget that cycles through three different
  199. options for the type of axes to be drawn.  The 'None' option results in
  200. no axes being drawn.  The 'Star' option results in standard axes being
  201. drawn with each axis crossing the other two at the origin.  The 'Box'
  202. option results in a rectangular box being drawn with the vertices equal
  203. to the Axes Span values.
  204.  
  205.  
  206. NOTE
  207.  
  208. This gadget is not implemented yet.  It will allow the user to store a
  209. comment about the plot.
  210.  
  211.  
  212. ------------
  213. PROJECT MENU
  214. ------------
  215.  
  216. This menu contains nine items.  Some of these are not yet implemented.
  217. The >> symbol to the left of some menu items indicates that these items
  218. have subitems.
  219.  
  220.  
  221. NEW
  222.  
  223. This is not yet implemented.  It will be used to reset all plotting
  224. parameters.
  225.  
  226.  
  227. OPEN
  228.  
  229. This item allows the retreival of stored files.  It has three
  230. subitems: All, Settings, and Picture.  Settings will retrieve only the
  231. settings displayed on the input window, Picture retrieves IFF ILBM
  232. graphics files, and All gets both. Picture is the only option
  233. currently implemented.  (I wanted to implement the Settings option
  234. before releasing the program, but other projects delayed the coding.
  235. I decided to go ahead and release the program without the option.)
  236.  
  237. When choosing Open, a file requester appears that is very much like the
  238. Deluxe Paint II requester.  It lists files and directories in a
  239. selection area.  The list can be scanned up or down by using the arrows
  240. or proportional gadget on the right side of the file selection area.  A
  241. directory can be chosen by clicking on the directory name or typing it
  242. in the Drawer gadget.  A file can be selected by clicking on the name
  243. or typing it in the File gadget.
  244.  
  245. You can change to df0: or df1: or dh: by choosing one of the boolean
  246. gadgets near the bottom of the requester.  The dh: gadget is unique, in
  247. that it is user modifiable.  If you type the name of a device, such as
  248. vd0:, in the Drawer gadget and then exit the requester, the dh: gadget
  249. will be a vd0: gadget the next time the requester is displayed.
  250. Beware, the gadget can only hold eight characters.
  251.  
  252. Once a file is selected, it can be loaded by clicking on the Load
  253. gadget, or it can be cancelled by clicking on Cancel.
  254.  
  255. The Load requester was originally written by Kevin Clague (Thanks!) and
  256. then modified extensively by Randy Finch.
  257.  
  258.  
  259. SAVE
  260.  
  261. This item allows the Settings, Picture, or All to be saved under the
  262. previously selected filename.  The picture is saved as an IFF ILBM
  263. graphics file that can be retrieved by Deluxe Paint and other graphics
  264. packages.  This item is not yet implemented.
  265.  
  266.  
  267. SAVE AS
  268.  
  269. This item works just like save except a requester identical to the
  270. Load requester is displayed so a new filename can be selected.  Only
  271. the Picture save option is implemented.  The picture is saved as an
  272. IFF ILBM graphics file that can be retrieved by Deluxe Paint and other
  273. graphics packages.
  274.  
  275.  
  276. COLOR
  277.  
  278. This item has three subitems: Adjust, Load, and Save.
  279.  
  280. Adjust displays a color requester on the Graph screen that allows the
  281. colors to be changed by the user.  The coding for this requester was
  282. done by R. J. Mical and appears in his ProSuite I.  Thanks to R. J. for
  283. making this available to the Amiga community.
  284.  
  285. The requester is similar to others you have seen.  The current color is
  286. displayed in a box in the upper left corner of the requester.  A set of
  287. RGB sliders appear along the top.  These can be changed to a set of HSL
  288. sliders by selecting one of the letters in RGB.  The color palette
  289. appears in the lower left corner and is arranged left to right, top to
  290. bottom.  3DPlot uses color 0 (upper left of color palette) for the
  291. background.  Color 1 is the border color.  Color 2 is the axes color.
  292. Color 3 will be used for text, but is not used in this version.  In low
  293. resolution, colors 4-27 (24 colors) are used for the graph (more about
  294. this later).  Colors 28-31 are not currently used.  In high resolution,
  295. colors 4-15 (12 colors) are used for the graph.
  296.  
  297. You can copy one color to another by choosing the color to be copied,
  298. choosing the Copy gadget, and then selecting the color to be copied to.
  299.  
  300. You can smoothly range a series of colors by choosing the Range
  301. gadget, then the first color of the range, and then the second color.
  302.  
  303. The Load and Save subitems will be used to load and save color palettes
  304. but they are not currently implemented.
  305.  
  306.  
  307. SCREEN
  308.  
  309. This item can be used to choose the screen resolution you wish to work
  310. with.  Options are low- and high-resolution, interlaced and non-
  311. interlaced, and overscan.  Overscan is not yet implemented.
  312.  
  313.  
  314. TITLE
  315.  
  316. This item simply toggles the title bar of the graph screen on and off.
  317. There is a bug when changing the screen resolution.  The title bar is
  318. always turned off when changing to a new resolution but the submenu
  319. remains in its previous state, whether on or off.
  320.  
  321.  
  322. PRINT
  323.  
  324. This item will be used to do a graphics dump to the printer but is not
  325. yet implemented.
  326.  
  327.  
  328. EXIT!
  329.  
  330. End the program.  NO WARNING is given.
  331.  
  332.  
  333. -------------
  334. FUNCTION MENU
  335. -------------
  336.  
  337. The Function menu contains four items.  All but one subitem is
  338. implemented.
  339.  
  340.  
  341. PLOT
  342.  
  343. This is the action item.  Choosing one of its subitems makes 3DPlot go
  344. to work.  The plot appears on a separate screen, the Graph screen.  The
  345. four plot options are: Normal, Hidden, Solid, and Contour.  Upon
  346. choosing one of these options, 3DPlot will calculate values of Z at
  347. various points within the plot range specified by the Plot Span gadgets
  348. on the input window.  Minimum and maximum distances from the viewer are
  349. determined and then split into either 24 or 12 equal ranges, depending
  350. on the screen resolution.  Plotting then begins.  (There could be a
  351. rather long delay before a plot begins if a large range and small
  352. spacing is chosen.  It is usually good to start with a rough quick plot
  353. and then do a detailed plot when all looks well.)  Far points will be
  354. plotted in color 4, near points will be plotted in color 27 or 15
  355. depending on the resolution, and points in the middle will be
  356. distributed between the intervening colors.
  357.  
  358. Normal causes the plot to draw lines along constant X or Y values or
  359. both based on the Surface gadget setting.  The lines are drawn
  360. separately and have a resolution based on the Plot Precision settings.
  361. This plot usually takes the longest.
  362.  
  363. Hidden draws the graph as a series of hollow (filled with background
  364. color) four-sided polygons starting with the fartherest corner and
  365. working forward.  The size of the polygons is determined by the Line
  366. Spacing gadgets settings.  Since each successive polygon appears in
  367. front of the previously drawn polygons, the graph will have hidden
  368. lines removed.
  369.  
  370. Solid is exactly the same as Hidden except the four-sided polygons are
  371. filled with the plot color rather than the background color.  This
  372. makes the graph appear as a solid figure.
  373.  
  374. Contour will draw a flat graph with no perspective, letting the graph
  375. colors define the shape of the graph.  This is not yet implemented.
  376.  
  377. Once the graph is drawn, the axes are drawn unless the Axes Type is set
  378. to None.
  379.  
  380.  
  381. STOP PLOT
  382.  
  383. Choosing this item after choosing a Plot option will interrupt the plot
  384. and return control to the user.
  385.  
  386.  
  387. SETTINGS
  388.  
  389. Selection of this item causes the Settings screen containing the input
  390. window to be brought to the front.
  391.  
  392.  
  393. GRAPH
  394.  
  395. Selection of this item causes the Graph screen containing the Plot (if
  396. one has been plotted) to be brought to the front.
  397.  
  398.  
  399. ---------
  400. TEXT MENU
  401. ---------
  402.  
  403. This menu contains several items for adding text to the plot screen.
  404. None of these items are implemented yet and are not discussed.
  405.  
  406.  
  407. ---------------
  408. CLOSING REMARKS
  409. ---------------
  410.  
  411. I hope you enjoy the program.  If you have any questions, you can write
  412. me or contact me on BIX.
  413.