                         Varmint's POV animator    
                              Version 1.0

                         Eric Jorgensen (1994)


                        Knowledge and Information

GNERAL INFO

  - Varmint's POV Animator (VPOVA) is FREE.  You can give it away, 
    but don't sell it.
  - VPOVA code is free too.  If you modify it, please give credit
    where it is due and call it something different than VPOVA. 
    

  - Eric's email address is:  smeagol@rt66.com
       *** Please send me email if you use this program.  ***

RUNNING VPOVA
  
  You will need:
    POVRAY executable
    POVRAY definition file (.def)
    POVRAY scene file (.pov)
    VPOVA  config file (.cfg)


  The command  line loooks like this:

    animate (scene file) [(config file)] [(arguments)]
         
  You must include a scene file.  The config file will default to
  "animate.cfg" if it is left out.  These are the valid arguments:

    -pov  [text]     pathname of POV executable  
    -def  [text]     pathname of .def file  
    -seed [text]     Seed name for output pics (must be 4 chars or less) 
    -pdir [text]     Picture Output directory  
    -pid  [text]     Id string for parsable lines  
    -sf   [number]   Number of starting frame  
    -ef   [Number]   Number of last frame to be rendered  
    -fps  [number]   Frames per second  
    -st   [number]   Time index (in seconds) of start frame  
    -args ["text"]   Arguments for the POV command line. (must be in quotes)  
    -h, -x           Help  (this list)  
    -debug           Set debug mode ON  
    -pause           Request keystroke after every frame  
    
  (Note:  arguments take precedence over config file assignments)

  Example:  
    Let's say you wanted to run VPOVA with a POV scene file
    named "chump.pov" and use a config file named "gump.cfg".  And you also
    wanted to start at frame 22 and add -V and -a0.1 to the POV command line. 
    
     animate chump.pov gump.cfg -sf 22 -args "-V -a0.1"


  When VPOVA is running, it generates a scene file called "anim.pov" based
  on the original scene file and the current frame.  This is then rendered
  by POV which passes control back to VPOVA when  it is done.

  OUTPUT:

    VPOVA sets up POVRAY so that it outputs a targa image for each frame.
    The image with have a name composed of a seed, frame number, and .tga
    extension.  eg: If the picture seed were "GILL", the filenames for 
    frames 98-102 would be:

      GILL0098.tga
      GILL0099.tga
      GILL0100.tga
      GILL0101.tga
      GILL0102.tga
  
THE CONFIG FILE

  You can specify all the arguments for VPOVA in a config file.  See the 
  file "example.cfg" too see what a config file looks like and some
  notes on how to use it.

  Note:  Command line arguments take precedence over config file arguments.

RUNNING THE EXAMPLES

  To run the example animation, you will first need to edit the file
  called "example.cfg" and change the pathnames for the pov executable,
  the pov def file, and the picture output directory to values that
  will work onyour system.  When you have done that, simple type this
  at the command prompt in the VPOVA directory:

     animate example.pov example.cfg


PROGRAMMING A SCENE FILE

  To generate an animation you will first need a POV scene file.  
  Animation commands start with the parse id string end with a newline
  character.  The default parse id strig is "//*", but you can define
  it to be anything you want.  The file "example.pov" contains a simple,  
  animation-ready scene file.

  DATA TYPES AND PARSE OUTPUT

    There are two data types used by VPOVA:  numbers and text.  The 
    data type of the starting element affects ow the entire line
    is parsed.  If the first item is text, te lie is parsed as text.
    If the first item is a number, te entire line is parsed as
    a number.  Here are some examples:

      //* "bob" + "glob"                =>   bobglob

      //* 1 + 2                         =>   3

      //* "bob" + 1 + 2                 =>   bob12

      //* 1 + "bob"                     =>   [ERROR]

      //* "" + 1 + "bob"                =>   1bob

  BASIC MATH OPERATORS (+,-,*,/)

     VPOVA supports these  basic math operators:

       + addition
       - subtraction
       / division
       * multiplication

     All operators must be separated spaces. 
     All four operators work with numbers. 
     Only the plus (+) operator works with text.
     Operator DO NOT follow algebraic order.

     Examples:

       //*  1 / 2                       =>   0.5

       //*  1 /2                        =>   [ERROR]

       //*  "bob" - "glob"              =>   [ERROR]

       //*  1 + 2 * 3                   =>   9

  CLUSTERS (Parenthesis operators)

    VPOVA uses a recursive algorythm to always parse item in 
    parenthesis first.  Any item or set of items contained in a set of
    parenthesis is called a "cluster."  Clusters are special because they
    are processed independently of the parse string that  contains them. 
    When a cluster is evaluated, it is turned into either a text or number 
    datatype.

    Examples:

      //* 1 + (2 * 3)                   =>   7

      //* "bob" + (1 + 2)               =>   bob3

      //* "bob" + (1 + (2 / 3))         =>   bob1.66666

  BOOLEAN OPERATORS (<,>,<=,>=,!=, ==)

    VPOV supports these basic boolean operators:

      <   less than
      >   greater than
      <=  less than or equal
      >=  greater than or equal
      !=  Not equal
      ==  equal

    To evaluate booleans, VPOV evaluates everything left of the operator,  
    then everything right of the operator.  Once evaluated, VPOVA turns
    the expression into a number data type tat contains either 1.0 for TRUE
    or 0.0 for FALSE.

    All six operators work for numbers.
    Only == and != work for text.

    Examples:

      //* 1.2 == 1.2                    =>   1.0

      //* 1.2 < 0.3                     =>   0.0

      //* "bob" == "bob"                =>   0.0

      //* "bob" == "b" + "ob"           =>   1.0

      //* "bob" <= "glob"               =>   [ERROR]

      //* ("bob" == "bob") + (2 == 2)   =>   2.0

  FUNCTIONS

    VPOVA functions start with the "@" character and are followed
    by a cluster containing arguments separated by commas.

    Single argument functions evaluate the entire argument cluster 
    before evaluating themselves.

    Multi argument functions will usually only evaluate arguments if they
    are contained in individual clusters.  This wil make more sense
    after the examples.

    Functions always evaluate into a number or text data type.  
    Function names are case insensitive. 
    
    MATH FUNCTIONS:

      VPOV has these single argument math functions: SIN,COS,TAN,ASIN,ACOS,
        ATAN, CEILING, FLOOR, INT, LOGN, LOG10, ABS

      Trig functions take radian arguments.

      Examples:

        //*  @sin(3.14159)              =>   0.0

        //*  @SIN(3.14159)              =>   0.0
        
        //*  @log10(10 * 10)            =>   2.0

        //*  @cos("bob")                =>   [ERROR]

    OTHER NUMBER FUNCTIONS:

      MOD(number1,number2) 
      RANDOM(number)

      MOD is a two argument function.  It converts it's arguments to
      intergers and returns te first argument modulus the second argument.

      RANDOM converts it's argument to an interger and generates a
        number >= 0 and < argument.

      Examples:

        //*  @mod(12,5)                 =>   2.0

        //*  @mod(12,2 + 3)             =>   [ERROR]

        //*  @mod(12,(2 + 3))           =>   2.0

        //*  @random(5)                 =>   1.0  (Could be any interger from
                                                   0 to 4.)

    MISCELLANEOUS FUNCTIONS:

      NUMTAG(#chars,number) 
      SET(name,value)
      FROMFILE(file name,line #, evaluation type)
      IF(argument,thencluster,elsecluster)

      NUMTAG is a two argument function that returns a text string with
      a number format similar to what VPOVA uses to name the output
      frames rendered by POV.  Thhe first argument specifies the number
      of chharacters to use.  The second argument contains the interger to 
      convert into a umber tag.   This is useful for including extrnal
      animation picture files.

      SET allows you to declare a dynamic variable.  This function is
      described in more detail below.

      FROMFILE extracts a line from an external file and evaluates it
      accroding to your specifications.  Valid arguments  for the 
      evaluation type are TEXT, NUMBER, and TOKEN.  (Case is important  
      here. It is also important to NOT put these words in parenthesis.)
      TOKEN indicates to VPOVA that it needs to evaluate the string it
      gets from the file as if it were a VPOVA instruction line.  This
      function is useful for including any sort of weird, nonstandard 
      stuff you like.

      IF allows you to perform logic decisions dynamically.  This function
      is described in more detail below.

      Examples:

        //*  "bif" + @numtag(4,22)      =>   bif0022

        (Assume we have a file called "gob.inp" that has these lines:)
               22.22
               "fred"
               22 + (2 * 2)
        
        //*  12 + @fromfile("gob.inp",1,NUMBER)   =>   34.22

        //*  @fromfile("gob.inp",2,TEXT) + "dy"   =>   freddy  
        
        //*  @fromfile("gob.inp",3,TOKEN)         =>   26.0

  WORDS and VARIABLES

    When VPOVA encounters any text without quotes, it assumes that it 
    mus be a predefined word or variable.  The words that VPOVA 
    supports are:

      TIME     Current animation time in seconds
      FRAME    Current animation frame number
      PI       3.1415926...

    To use a word just included it plain text in a instruction line.
    Words are case sensitive.

    Examples:

      //*  2 + PI                       =>   5.1415926

      //*  @sin(PI)                     =>   0.0

      //*  @sin(pi)                     =>   [ERROR]

    DYNAMIC VARIABLES   

      VPOVA allows you to declare and alter dynamic variables.  To do this,
      you use a special function called "SET".  The first argument for set
      is the name of the variable (without quotes), and the second argument
      is the value to assign.  (VPOVA automatically figures out the  
      datatype of the value.)


      Examples:

        //*  @set(foo,27.0)
        //*  12 + foo                   =>   39.0

        //*  @set(foo,("blob" + 1))
        //*  foo                        =>   blob1

        //*  @set(foo,1.0)
        //*  @set(foo,(foo + 1.0))
        //*  foo                        =>   2.0

  BRANCHING WITH THE IF FUNCTION

     VPOVA allows you to perform dynamic logic branches in an animation with
     the IF function.  This function evaluates it's first argument (a number)
     and then evaluates the second (then) argument if the first argument is
     non-zero ot the third argument (else) if the first argument is zero.

     The then and else arguments *MUST* be clusters!  If the then and else 
     arguments are not in parenthesis, the results will be unpredictable.

     Examples:  (The frame # for these examples is 22)

       //*  @if(1.0,(FRAME),(27))            =>   22.0

       //*  @if((FRAME < 12),(FRAME),(27))   =>   27.0

       //*  @if(0.0,(FRAME),())              =>   

       //*  @if(1.0,("blob" + glob"),())     =>   blobglob

       //*  1 + @if(0.54,(7),(0))            =>   8.0

 

HINTS AND TIPS

  - The -debug command line argument will cause VPOVA to go ahead and
    generate the scene files, but not render them.  It is recommended  
    that you first run your animation with the -debug option since it
    will quickly determine wether VPOVA will choke at any point on the
    scene file during the animation.

  - It is a good idea to also render a single frame (set the start frame
    and end frame to the same number) before you actually render the
    whole thing.

  - Use TIME instead of FRAME for equations of motion.  This will enable you 
    to quickly render animations by reducing the frame rate.

  - VPOVA never erases the anim.pov file it creates, so you can examine this
    file post mortem for any clues when debugging.

  - Since you can define the parse id string,  you can include multiple 
    animations in a single file.  ie:  All the animations commands
    for one animation could start with "//A"  and all the commands
    for another animation can start with "//B".




Well, that is it folks.  I hope you enjoy my program.  


