home *** CD-ROM | disk | FTP | other *** search
/ AMIGA PD 1 / AMIGA-PD-1.iso / Magic_Illusions / Amiga / Tools / MK3D / mk3d.doc < prev    next >
Text File  |  1994-01-08  |  12KB  |  301 lines
  1. Document mk3d.doc
  2.  
  3.                 X       X       X       X       X       X     
  4.          8!!AK4Dm!!AK4Dm!!AK4Dm!!AK4Dm!!AK4Dm!!AK4Dm!!AK4Dm!!AK
  5.          ry=8>p+Ry=8>p+Ry=>pj+Ry>p"jy>'[jyD5>[jyD$5>J[jy$5>J[jy
  6.          sM?&E/)_M?&E/)_M?E/)j_?E/@)?Ef@)]g?f@a)g??ff@)Og?ff@)O
  7.          yY-PM-e>Y-PM-e>Y-M-e>Y-M-Be-M-Bw"e-M-B"e)-MW-"e4)MW-"e
  8.          \7.\<.Ok7.\<.Ok7.<.+k7z<.p+z<,p+MHz,px+Hz{,gp+sH{,gp+s
  9.          2$!YZ,M|$!YZ,M|$!Z,pM|$Z,Sp$Zvjp$aXZjp$a[XZFjp$[XZFjp$
  10.          =D)<qGyuD)<qGyuD)<qGyuD)<qGyuD)<qGyuD)<qGyuD)<qGyuD)<q
  11.  
  12.  
  13. So, ya wanna make 3-d pictures using random stereo-whatsis technology, but
  14. using a text format so your BBS friends can enjoy it.  Well... this is the
  15. program for you.
  16.  
  17. Another fine product of The Cheese Olfactory Workshop.
  18.  
  19. 0. Introduction
  20. ---------------
  21.  
  22. Believe it or not, the basic idea of how to make these images has been
  23. around for several years.  According to _Magic Eye_ "A New Way of Looking
  24. at the World" (Copyright 1993 by N.E. Thing Enterprises, 
  25. ISBN: 0-8362-7006-1):
  26.  
  27.   "During the 1960s, Dr. Bella Julesz was the first to use
  28.    computer-generated 3D images made up of randomly placed dots to study
  29.    depth perception in human beings.  Because the dot pictures did not
  30.    contain any other information, like color or shapes, he could be sure that
  31.    when his subject saw the picture it was 3D only!"
  32.  
  33. Today, however, the technology seems to have gone crazy.  The book
  34. mentioned above contains several very nice images you can freak your eyes
  35. out over (the rose seems to be a particular favorite amongst most of the
  36. people I know).
  37.  
  38. Of course, trying to transmit something as detailed as one of THOSE
  39. pictures would require bundling the resulting stereogram as one of your
  40. favorite little file standards (pick a standard.. ANY standard) uuencoding
  41. the monster, then hoping the person on the other side has the software
  42. necessary to undo the mess.
  43.  
  44. Well.. that's fine.
  45.  
  46. This program doesn't come close to the detail you can get with a really
  47. nice program that actually uses real dots, instead of the synthetic ones
  48. we're going to be working with <snort>, but this software will let you
  49. transmit your little creation over E-mail, to a printer, through your
  50. cat's whiskers, and to Alpha-Centari.  In short, this program can create
  51. an ASCII 3-d image.  And we all know how interchangable ASCII is.  Don't
  52. we?
  53.  
  54. 0.1. The Author
  55. ---------------
  56.  
  57. I don't have the slightest idea who originally wrote this program.  I
  58. caught a post off Usenet one day gave away some C code for a program
  59. called 'mk3d' (which, at least in name, I stuck with).  There was a binary
  60. with it called mk3d.exe, which meant, to me, that it had been compiled for
  61. MS-DOS <plegh>.
  62.  
  63. However, since I'm an anal-retentive programmer with too much time on my
  64. hands this vacation, and I don't feel like messing with my other pet
  65. projects, I decided to convert the C source to Amiga E, and add a bunch of
  66. nifty features (well, a few anyway).  After becoming bald, I managed to
  67. get the damned images to pop up the way they should.  E is a nice
  68. language, but I swear, trying to convert from C can be a damning
  69. experience.
  70.  
  71. As for myself, I'm merely a college student, 26 years old, working towards
  72. my Bachelor of Arts in Music (emphasis on Composition).  My senior project
  73. and its recital will be due by 5 Feb 95, by which time, hopefully, I will
  74. have released the .MID versions for the general public to scorn me over
  75. (my project has to be a composition, the recital of which will be
  76. performed by an Episcopal church choir I've been working with, and their
  77. organist.. pretty good performers, really).
  78.  
  79. The computers thing is something I picked up as a kid, and never really
  80. quite let go of.
  81.  
  82. 0.2. The Documentation
  83. ----------------------
  84.  
  85. The documentation for this program will hopefully be more detailed than
  86. the documentation I got for the MS-DOS version of mk3d.  I converted it over
  87. to AmigaGuide format for those who like that, and put in a whole bunch of
  88. BS (like what you are reading now) for those who are desperate to read
  89. stuff.
  90.  
  91. My e-mail address is jvanriper@uncavx.unca.edu (at least, until I finish
  92. school).
  93.  
  94. Special thanks to the author of text2guide (Stephan Sürken).  I wish I
  95. could kiss you.
  96.  
  97. 0.3. Distributability
  98. ---------------------
  99.  
  100. This software is freely distributable.  Even the source code has been
  101. released.  I am returning it to the public, since I got it from the
  102. public.
  103.  
  104. Heed my example.
  105.  
  106. 0.4. Disclaimers
  107. ----------------
  108.  
  109. All applicable disclaimers apply.  You didn't pay for this, so don't come
  110. screaming to me that you've overwritten your s:startup-sequence file with
  111. a stereogram, or that your big proposal that you've been slaving over for
  112. five years doesn't look very pretty in 3-d.  This software (as far as I
  113. can tell) is pretty stable, and should do its job provided you do your job
  114. in protecting your system from yourself and others.
  115.  
  116. In any event:
  117.  
  118. I, Joseph E. Van Riper III, and my company, the Cheese Olfactory Workshop,
  119. refuse to accept responsibility for the results of this program in any
  120. way, shape, or form.  Use of this program assumes responsibility on the
  121. user's part.
  122.  
  123. 1. The Program
  124. --------------
  125.  
  126. mk3d was originally written in C, and compiled for MS-DOS.  The code has
  127. been re-written for Amiga E, thus the binary is smaller and better than the
  128. original C counterpart's binary.
  129.  
  130. Since this was written in E, you don't need to worry about stacksize, and
  131. arguments are handled according to the standard AmigaDOS way (ReadArgs). 
  132. As far as I know, this program will run on any Amiga system.
  133.  
  134. Original .EXE executable for MS-DOS:
  135.  
  136.   ------rw-d    18368  02-Sep-93 15:56:56  mk3d.exe
  137.  
  138. Amiga E executable for AmigaDOS (with added bells and whistles):
  139.  
  140.   ------rwed     7616  08-Jan-94 15:05:46  mk3d
  141.  
  142. Now.. given these stats, would you want an Amiga or an IBM-PC clone?
  143.  
  144. 1.1. Using mk3d
  145. ---------------
  146.  
  147. As with any program using ReadArgs, using a question mark as an argument
  148. will call up a template that might help you figure out the option you're
  149. looking for:
  150.  
  151. ---------------
  152.  
  153. > mk3d ?
  154.  
  155. IN=INPUT/A,OUT=OUTPUT,ERR=ERRORS/K,S=SIMPLE/N/K:
  156.  
  157. ---------------
  158.  
  159. Upon getting this, you can type another question mark for more detailed
  160. instructions:
  161.  
  162. ---------------
  163.  
  164. IN=INPUT/A,OUT=OUTPUT,ERR=ERRORS/K,S=SIMPLE/N/K: ?
  165.  
  166. Usage: mk3d IN "filename" [OUT "filename"] [ERR "filename"]
  167.             [S "number"]
  168.  
  169.  IN specifies a mandatory input file to read for a template.
  170. OUT specifies an optional output file to write.
  171. ERR specifies an optional error file to write (instead of stderr).
  172.   S specifies how simple the characters should be, by this chart:
  173.  
  174.       0 = Only uppercase characters
  175.       1 = Upper/lowercase characters
  176.       2 = AlphaNumeric characters
  177.       3 = AlphaNumeric characters with symbols (default)
  178.       4 = Anything from value 1 to 255
  179.  
  180. For information about the IN file's format, please, read mk3d.doc.
  181. NOTE: This program based on the same written for MS-DOS.
  182.       Modified somewhat heavily by Joseph E. Van Riper III
  183.       of the Cheese Olfactory Workshop.
  184.  
  185. ---------------
  186.  
  187. Generally, those instructions should be enough.
  188.  
  189. 1.1.1. INPUT
  190. ------------
  191.  
  192. Simply put, this refers to the file you want to read.  This parameter MUST
  193. be filled (although you don't have to actually type 'mk3d input fulu.stx'..
  194. you could just say 'mk3d fulu.stx').  If this parameter is missing, you'll
  195. see the extra helps screen and a little error message.  Read
  196. `The Input File' for more information.
  197.  
  198. 1.1.2. OUTPUT
  199. -------------
  200.  
  201. Simply put, this refers to the file you want to create.  This parameter is
  202. optional.. if it isn't filled, stdio is used (therefore, you can redirect
  203. the output).  This option doesn't really have to be spelled out.. it can
  204. be inferred as the name following the INPUT's filename (eg: you can type
  205. 'mk3d infile.stx outfile.asc' or 'mk3d infile.stx output outfile.asc').
  206.  
  207. 1.1.3. ERRORS
  208. -------------
  209.  
  210. This parameter lets you see whatever mk3d sees as a picture.  This is in
  211. case you've got a bunch of funky weirdness you're trying to do with other
  212. characters that mk3d doesn't recognize, but you want to create a picture
  213. out of.  Using this parameter shows what mk3d is using, changing unknown
  214. characters to spaces.
  215.  
  216. It's called 'ERRORS' because it originally redirected the stderr port.  I
  217. decided that was a bad practice <grin>.
  218.  
  219. ERROR's default is NIL:.  You MUST use the keyword to change ERROR's
  220. default (eg: 'mk3d infile.stx outfile.asc error CONSOLE:' is okay, but
  221. 'mk3d infile.stx outfile.asc CONSOLE:' will not work).
  222.  
  223. NOTE: CONSOLE: can be thought of as the stderr device.
  224.  
  225. 1.1.4. SIMPLE
  226. -------------
  227.  
  228. The SIMPLE parameter takes a number that will change the kind of
  229. characters that are used to generate the 3-d image.  If you wish to use
  230. this parameter, you MUST specify it (eg: 'mk3d infile.stx outfile.asc s 0'
  231. but not 'mk3d infile.stx outfile.asc 0' -- note also, 's' is a shortcut for
  232. SIMPLE).
  233.  
  234.  0 - Yeilds only uppercase characters.  This might be handy for those
  235. potentially existent people who are limited to modems that cannot output
  236. lowercase characters... or for similiar reasons.  Very quick execution.
  237.  
  238.  1 - Yeilds upper/lowercase characters.  Any character in the alphabet,
  239. whether lowercase or uppercase, may be used to create the images.  Medium
  240. execution.
  241.  
  242.  2 - Yeilds AlphaNumeric characters.  Upper and Lowercase characters of the
  243. alphabet, as well as numbers, can appear.  Slow execution.
  244.  
  245.  3 - Yeilds as 2, but may also have various punctuation characters.  Very
  246. quick execution. Also the default.
  247.  
  248.  4 - Yeilds anything from character 1 to character 255.  Very hard to
  249. display for most terminals.  Definately would require a special program to
  250. read.  In fact, this is almost completely unusable, but is included in
  251. case someone figures out a way to deal with it.  Remember, at the end of
  252. each 'line' is a '10' character.. although the 10 character itself may be
  253. used as a character according to this setting.  Your program would have to
  254. know when to wrap the new line according to how many columns you're
  255. supposed to have in the image.
  256.  
  257. The more variety in characters, the less likely a chance for ambiguity in
  258. the imagine process.  That's why I even bother with an option 4.
  259.  
  260. NOTE: if you choose a number higher than 4, the program defaults to 3.
  261.  
  262. 2. The Input File
  263. -----------------
  264.  
  265. If you want to create your own images, you have to follow a special
  266. format.
  267.  
  268. The first line contains a number that represents the 'Gramwidth', or the
  269. maximum number of columns to go across the screen (to put it simply).  So,
  270. if you want something that can be viewed by most terminals, choose '79'. 
  271. If you have a compressed type on your printer, and you want to print out a
  272. large 3d image, you can figure out how many columns are available on the
  273. printer and use that.  Or, perhaps you have a nice font on your Amiga that
  274. you can use.
  275.  
  276. However, the Gramwidth must be between 1 and 512.  How someone thinks they
  277. could make a nice stereogram with only 3 columns is beyond me.
  278.  
  279. The next line is the Xdepth value.  This number comes between 5 and 64,
  280. and must be less than half of the Gramwidth.  Which, using math, means that
  281. you must really have a Gramwidth of 11 - 512... but I programmed this part
  282. according to the original code.  Sloppy programmers...
  283.  
  284. I haven't really played with the Xdepth values, but with a Gramwidth of 79
  285. its been recommended to use an Xdepth of 16.  I suspect this would control
  286. how much depth there is between layers.
  287.  
  288. After this, you can actually create the image you want.  The only
  289. characters that mk3d looks for, from this point on, are carraige returns
  290. (which, obviously, goes to the next line), and numbers from 1 to 9. 
  291. Everything else is considered 'background' characters, and ignored.
  292.  
  293. The characters 1-9 represent different layers.  A '1' will sit on the layer
  294. that's closest to the background, but just above it. '2' sits just above a
  295. '1'... and so on down the line, until '9' is the very top-most layer you
  296. can work with.  Therefore, careful readers will note that you have 10
  297. layers to work with!  That's as deep as it goes with this program.. sorry.
  298.  
  299. Examine the different input files included with the archive to get a feel
  300. for how the program works.
  301.