home *** CD-ROM | disk | FTP | other *** search
/ Stars of Shareware: Raytrace & Morphing / SOS-RAYTRACE.ISO / programm / utility / dos / rotate / rotate.txt < prev    next >
Encoding:
Text File  |  1994-06-10  |  6.2 KB  |  190 lines
  1.                         Rotation Generator v0.1
  2.                   Copyright (c) 1994 Spencer Collyer
  3.                  This program is freely distributable
  4.  
  5. Overview
  6. --------
  7. ROTATE is a program to generate the rotation and translation vectors required
  8. to make an object at a given position point towards or away from another
  9. position.
  10.  
  11. Examples of where you might want to use it are:
  12.  
  13.  o If you have a sphere with a set of spikes sticking out of it, you want
  14.    the spikes to seem to project from the centre of the sphere
  15.    
  16.  o If you have a spotlight object (not a POV-Ray 'spotlight'!), you want it
  17.    to point in the same direction as the spotlight beam that comes out of it
  18.    
  19.  o If you have a rocket blasting away from a launch pad, you want to make sure
  20.    it looks like it has flown directly away from the launch pad
  21.    
  22. ... and basically anywhere else that you want to primary axis lined up on some
  23. point.
  24.  
  25. ROTATE generates POV-Ray 2.0 compatible files, which you can include into your
  26. own POV scenes.
  27.  
  28.  
  29. Important Note
  30. --------------
  31. This is a beta release of ROTATE.  There are probably bugs in it.  There are
  32. certainly improvements that could be made.  I'm releasing this version to get
  33. feedback from people on how it works.  Please let me know if you use it, what
  34. you think of it, any improvements you would like or bugs you find.
  35.  
  36. I can be reached on CIS in the GRAPHDEV forum - ID 100137,230
  37.  
  38.  
  39. Usage
  40. -----
  41. Run ROTATE with the command line:
  42.  
  43.     ROTATE [options]
  44.  
  45. The available options are:
  46.  
  47.     -i<name> - Specifies input filename.  If not given, defaults to
  48.                DATA.ROT.
  49.     -o<name> - Specifies output filename.  If not given, defaults to
  50.                ROTATE.INC.
  51.     -f[odi]  - Specifies output file format.  Formats are:
  52.                  o - Object format
  53.                  d - Declare format
  54.                  i - Object-Declare format
  55.                Default is '-fo'
  56.     -pn      - Specifies precision to use when outputting data.
  57.                Default is 3 dps.
  58.  
  59.  
  60. Input File
  61. ----------
  62. ROTATE takes an input file with the following format:
  63.  
  64. <align><axis> <objname> <x-pos> <y-pos> <z-pos> <x-aim> <y-aim> <z-aim>
  65.  
  66. where
  67.  
  68.     <align>     Is the alignment of the object along the appropriate axis.
  69.                 This can have values of '+' or '-', where '+' will make the
  70.                 object point away from the aim point, and '-' will make
  71.                 the object point towards the aim point.
  72.                 
  73.     <axis>      Is the primary axis of the object.  It is assumed that all
  74.                 objects have a primary axis, which is aligned along one of
  75.                 the main axes of the coordinate system.
  76.                 
  77.     <objname>   Is the name of the object.  Note that ROTATE does not 
  78.                 remember object names from line to line, so in some of the
  79.                 output modes, if you give the same object name twice, the
  80.                 second definition will override the first (although both
  81.                 will be output).
  82.                 
  83.     <x-pos>     Are the <x,y,z> position of the object.  Note that all
  84.     <y-pos>     objects should be defined at the origin, and ROTATE will
  85.     <z-pos>     generate the translation to place them at their correct
  86.                 positions.
  87.                 
  88.     <x-aim>     Are the <x,y,z> position of the aim point, i.e. the point
  89.     <y-aim>     through which the (extended) primary axis of the object
  90.     <z-aim>     should pass, once the object is in its proper position.
  91.     
  92. Any line that starts with a ';' will be treated as a comment, and the whole
  93. line will be ignored.
  94.  
  95. Note that there should be no spaces between the <align> and <axis> elements
  96. of each line.
  97.  
  98.  
  99. Output Files
  100. ------------
  101. ROTATE can produce output in one of three formats, all of which are designed
  102. to be included into a POV-Ray scene file.  To give a concrete example on which
  103. to work, each format will be given with the output it would produce if the
  104. following input line was presented:
  105.  
  106. +x Arrow_X 10.00 11.00  9.00  5.00  4.00  3.00
  107.  
  108.  
  109. Object Format:
  110. In this format, each line in the input file will cause the following output
  111. to be generated:
  112.  
  113.   object
  114.   {
  115.         <objname>
  116.         rotate <rotate-vector>
  117.         translate <x-pos, y-pos, z-pos>
  118.   }
  119.   
  120. The example line would look like this:
  121.  
  122.   object
  123.   {
  124.         Arrow_X
  125.         rotate < 0.000, -34.895, 54.462 >
  126.         translate < 10.000, 11.000, 9.000 >
  127.   }
  128.  
  129.  
  130. Declare Format:
  131. In this format, each line in the input file will cause the following output
  132. to be generated:
  133.  
  134.   #declare <objname>_R = <rotate-vector>
  135.   #declare <objname>_T = <x-pos, y-pos, z-pos>
  136.   
  137. The example line would look like this:
  138.  
  139.   #declare Arrow_X_R = < 0.000, -34.895, 54.462 >
  140.   #declare Arrow_X_T = < 10.000, 11.000, 9.000 >
  141.   
  142. These declarations can then be used in a scene file as the parameters to rotate
  143. and translate keywords (with the '_R' for rotate, the '_T' for translate).
  144. This format would be useful if, for instance, you wanted a set of objects to
  145. be aligned parallel with each other, with one of them lined up on a given aim
  146. point.
  147.  
  148. Note that, in this format, specifying the same <objname> twice will cause two
  149. sets of #declare's to be generated, the second of which will overwrite the
  150. first.
  151.  
  152.  
  153. Object-Declare Format:
  154. In this format, each line in the input file will cause the following output
  155. to be generated:
  156.  
  157.   #declare <objname>_Def = 
  158.       object
  159.       {
  160.           <objname>
  161.           rotate <rotate-vector>
  162.           translate <x-pos, y-pos, z-pos>
  163.       }
  164.       
  165. The example line would look like this:
  166.  
  167.   #declare Arrow_X_Def = 
  168.       object
  169.       {
  170.           Arrow_X
  171.           rotate < 0.000, -34.895, 54.462 >
  172.           translate < 10.000, 11.000, 9.000 >
  173.       }
  174.       
  175. Note that, in this format, specifying the same <objname> twice will cause two
  176. #declare's of <objname>_Def to be created, the second of which will overwrite
  177. the first.
  178.  
  179.  
  180. Examples
  181. --------
  182. There is an example TESTROT.ROT file in the ZIP file, along with TESTROT.POV
  183. to display the output.  To generate the example TESTROT.INC file required by
  184. TESTROT.POV, use the following command line:
  185.  
  186.   rotate -itestrot.rot -otestrot.inc
  187.   
  188. Then run POV-Ray against TESTROT.POV.
  189.  
  190.