                        Rotation Generator v0.1
                  Copyright (c) 1994 Spencer Collyer
                 This program is freely distributable

Overview
--------
ROTATE is a program to generate the rotation and translation vectors required
to make an object at a given position point towards or away from another
position.

Examples of where you might want to use it are:

 o If you have a sphere with a set of spikes sticking out of it, you want
   the spikes to seem to project from the centre of the sphere
   
 o If you have a spotlight object (not a POV-Ray 'spotlight'!), you want it
   to point in the same direction as the spotlight beam that comes out of it
   
 o If you have a rocket blasting away from a launch pad, you want to make sure
   it looks like it has flown directly away from the launch pad
   
... and basically anywhere else that you want to primary axis lined up on some
point.

ROTATE generates POV-Ray 2.0 compatible files, which you can include into your
own POV scenes.


Important Note
--------------
This is a beta release of ROTATE.  There are probably bugs in it.  There are
certainly improvements that could be made.  I'm releasing this version to get
feedback from people on how it works.  Please let me know if you use it, what
you think of it, any improvements you would like or bugs you find.

I can be reached on CIS in the GRAPHDEV forum - ID 100137,230


Usage
-----
Run ROTATE with the command line:

    ROTATE [options]

The available options are:

    -i<name> - Specifies input filename.  If not given, defaults to
               DATA.ROT.
    -o<name> - Specifies output filename.  If not given, defaults to
               ROTATE.INC.
    -f[odi]  - Specifies output file format.  Formats are:
                 o - Object format
                 d - Declare format
                 i - Object-Declare format
               Default is '-fo'
    -pn      - Specifies precision to use when outputting data.
               Default is 3 dps.


Input File
----------
ROTATE takes an input file with the following format:

<align><axis> <objname> <x-pos> <y-pos> <z-pos> <x-aim> <y-aim> <z-aim>

where

    <align>     Is the alignment of the object along the appropriate axis.
                This can have values of '+' or '-', where '+' will make the
                object point away from the aim point, and '-' will make
                the object point towards the aim point.
                
    <axis>      Is the primary axis of the object.  It is assumed that all
                objects have a primary axis, which is aligned along one of
                the main axes of the coordinate system.
                
    <objname>   Is the name of the object.  Note that ROTATE does not 
                remember object names from line to line, so in some of the
                output modes, if you give the same object name twice, the
                second definition will override the first (although both
                will be output).
                
    <x-pos>     Are the <x,y,z> position of the object.  Note that all
    <y-pos>     objects should be defined at the origin, and ROTATE will
    <z-pos>     generate the translation to place them at their correct
                positions.
                
    <x-aim>     Are the <x,y,z> position of the aim point, i.e. the point
    <y-aim>     through which the (extended) primary axis of the object
    <z-aim>     should pass, once the object is in its proper position.
    
Any line that starts with a ';' will be treated as a comment, and the whole
line will be ignored.

Note that there should be no spaces between the <align> and <axis> elements
of each line.


Output Files
------------
ROTATE can produce output in one of three formats, all of which are designed
to be included into a POV-Ray scene file.  To give a concrete example on which
to work, each format will be given with the output it would produce if the
following input line was presented:

+x Arrow_X 10.00 11.00  9.00  5.00  4.00  3.00


Object Format:
In this format, each line in the input file will cause the following output
to be generated:

  object
  {
        <objname>
        rotate <rotate-vector>
        translate <x-pos, y-pos, z-pos>
  }
  
The example line would look like this:

  object
  {
        Arrow_X
        rotate < 0.000, -34.895, 54.462 >
        translate < 10.000, 11.000, 9.000 >
  }


Declare Format:
In this format, each line in the input file will cause the following output
to be generated:

  #declare <objname>_R = <rotate-vector>
  #declare <objname>_T = <x-pos, y-pos, z-pos>
  
The example line would look like this:

  #declare Arrow_X_R = < 0.000, -34.895, 54.462 >
  #declare Arrow_X_T = < 10.000, 11.000, 9.000 >
  
These declarations can then be used in a scene file as the parameters to rotate
and translate keywords (with the '_R' for rotate, the '_T' for translate).
This format would be useful if, for instance, you wanted a set of objects to
be aligned parallel with each other, with one of them lined up on a given aim
point.

Note that, in this format, specifying the same <objname> twice will cause two
sets of #declare's to be generated, the second of which will overwrite the
first.


Object-Declare Format:
In this format, each line in the input file will cause the following output
to be generated:

  #declare <objname>_Def = 
      object
      {
          <objname>
          rotate <rotate-vector>
          translate <x-pos, y-pos, z-pos>
      }
      
The example line would look like this:

  #declare Arrow_X_Def = 
      object
      {
          Arrow_X
          rotate < 0.000, -34.895, 54.462 >
          translate < 10.000, 11.000, 9.000 >
      }
      
Note that, in this format, specifying the same <objname> twice will cause two
#declare's of <objname>_Def to be created, the second of which will overwrite
the first.


Examples
--------
There is an example TESTROT.ROT file in the ZIP file, along with TESTROT.POV
to display the output.  To generate the example TESTROT.INC file required by
TESTROT.POV, use the following command line:

  rotate -itestrot.rot -otestrot.inc
  
Then run POV-Ray against TESTROT.POV.

