 17. Wheel Template Structure
 ============================
 
                          Wheel template files
			  ====================

Overview:
			  
Gerber format does not specify the apertures of the wheel.
To overcome this problem, CAD systems output a description of the
apertures, often as a table to be read by the manufacturer.
To input this file by hand to a CAM system is not the preferred method
due to (1) operator time and (2) the possibility of human error while typing in
numbers.

To overcome these difficulties, Genesis 2000 has a system whereby the user
describes the structure of these wheel aperture files and the system translates
wheel files according a description of these files.
   
In the case that a textual wheel description is impossible (e.g. binary files), 
a second mechanism is provided for running user programs which translate 
the wheel into a common format recognized by Genesis 2000, and immediately 
input into the database.

A third mechanism is provided for identifying the format of the particular
wheel file, so the user does not have to specify the format of the customer
wheel file -- as long as the system has already been taught the wheel format.
       
   Description : 
    
      Each wheel template is a either:
      (a) A description of the form of a wheel file output
          by a CAD product.
      (b) A user program which translates a wheel file into
          a ``wheel file with text reference'', which is described
          below.
      
   Structure   :
    
      Headline file : /fw/lib/whltemps/wwww/headline
       
         Description :
	  
            This file contains the headline of the wheel table
	    which is output by the CAD product.  This file
	    should be copied from the headline of an example
	    of a wheel file.  This file may be empty if the
	    table has no headline, but empty headline files
	    significantly reduce performance of file identification.
	    This file is required for both (a) and (b).
    
	    If the headline file begins with: "KEYWORDS:" then the file
	    is taken to be a list of keywords separated by spaces one of which
	    must appear in the file in order to be of the appropriate
	    format.  This option is recommended for use only in the case that
	    the file has no headline.
	    
	    The headline file is case insensitive and treats two or more spaces
	    as any of one or more spaces.
	    
         Example   : /fw/lib/whltemps/wwww/headline
	  
             D-CODE  SHAPE   SIZE(Y)   SIZE(X)

	 Example   : /fw/lib/whltemps/dosn.3/headline
	  
             KEYWORDS:LINE_DRAW 
	     
	     As of Genesis version 1.3, the headline file may contain
	     more than one line of the types described above.  This
	     causes template to be matched if _any_ of the headlines
	     is found in the user wheel.
	 
      User program file : /fw/lib/whltemps/wwww/program.<sysname>
       
         Where <sysname> is what is returned by uname() in the sysname
	 field.  (For HP700, HP-UX, For Sun, SunOS) 
	 One such program is required for each seperate system that
	 the program must run on.  Therefore, if the user wishes this
	 translation to work on both Sun and HP, he must compile the
	 program on both, and name them "program.HP-UX", and 
	 "program.SunOS".  These files are used only in case (b)
	  
	 The program must output a ``wheel file with text reference''
	 with lines of the following form:
	  
	 dcode4  r10               1
         dcode5  s8.5              2
         dcode6  thr76x56x135x4x20 5
	 dcode7  di71x51           5
	 dcode10 rect16x84         6
	 dcode11 rect16x84x4	   7
	 dcode15 donut_r100x50    10 
	 dcode16 oval180x60       11
	  
	 where the first column is the dcode, the second is the genesis 
	 symbol, and the third column is the line in the source file.
	  
	 Example   :
	  
	    Omitted
	     
      Example file : /fw/lib/whltemps/wwww/example
	  
         Description :
	  
            This file contains an example file of a wheel output
	    by the CAD product.  It is currently unused by
	    Genesis, and exists for viewing by the user.
	     
	 Example   :
	  
	     Omitted
	      
      Template file : /fw/lib/whltemps/wwww/wtp

         Description :
	  
	    This file describes the form of a wheel file output
	    by a CAD product.  This is required in case (a).
	     
	 Example   :
	 
            SHAPE:ROUND
	    ###################
	    syn:<INT=DCODE> <b> CIRCLE, <FLOAT=SIZE>

            SHAPE:SQUARE
	    ###################
	    syn:<INT=DCODE> <b> IMAGE,SQUARE, <FLOAT=SIZE> 

            SHAPE:RECT
	    ###################
	    syn:<INT=DCODE> <b> RECTANGLE, <FLOAT=D> <CHAR> <FLOAT=E> 
	    sem:WIDTH=D;HEIGHT=E;

            SHAPE:R_THERMAL
            ###################
            syn:<INT=DCODE> <b> T, <FLOAT=D> X <FLOAT=E> X <FLOAT=F> X <INT=G> 
            sem:OSIZE=D;ISIZE=E;GAP=F;ANGLE=G(UNITS=45 DEGREE)
            con:SPOKES=4
            con:STYLE=ROUND
	    
	 Structure :
	  
            Header :

	       OPEN_CHAR=<           # any character
	       CLOSE_CHAR=>          # any character
	       MAX_RECS_PER_LINE=1   # The maximal dcode records per line
	       NUMBERING=EXPLICIT    # Options:
	                             # EXPLICIT - The dcode numbers appear 
	                             # 	      explicitly in the record.
	                             # STD      - Standard enumeration.
	                             # (10-19,70,71,20-29,72,73,30-69,74,75,...)
	                             # ORD4     - (4, 5, 6,...)
	                             # ORD10    - (10, 11, 12,...)
	                             # ORD      - (4, 5, 6,...) (same as ORD4)
				     # STATION  - Standard enumeration
				     #            according to station number
	       DEFAULT_UNITS=1+0MIL  # <optional multiplier> <+/->
	                             # <optional constant> MIL|INCH|MM
	       ROTATION_UNITS=1      # To Arrive at degrees
	       OUT_OF_RANGE_POLICY=  # Options:
	                             # MOVE_1000 (default) -
	                             #    Move decimal point either three places
	                             #    to the right or three places to the
				     #	  left if the values in the customer
				     #	  wheel file are out of range.
				     #    Works only if all units in template
				     #    are the same.
				     #    (except angle, rotation, and count)
				     # STAY -
				     #    Out of range apertures are reported
				     #    as unknown features.
	       CONDITIONAL_UNITS=    # This is a special feature for enabling
	                             # the choosing of units of a template
				     # according to what is written in the
				     # user wheel.
				     # Syntax:
				     #  <optional multiplier> <+/->
	                             #  <optional constant> MIL|INCH|MM
				     #  <<"match string">>
				     # e.g.
				     #    CONDITIONAL_UNITS=MM <"Units: MM">
				     #    CONDITIONAL_UNITS=INCH <"ENGLISH">
				     # Any number of ``CONDITIONAL_UNITS''
				     # may be specified.
				     # The match string is not case sensitive.
	       FREE_BLANKS=FALSE     # This is a special feature for enabling
				     # writing template without using the <B>
				     # element. In case of TRUE, the system
				     # will put <B> automatically before each
				     # element that starts with open-char, during
				     # the translation.
	                             # <optional constant> FALSE|TRUE
					     

               note: the above values are all defaults

            Comments :

               # Any line beginning with `sharp'

	       
            Record :
	    
	       A ``SHAPE'' line followed by a ``syn'' line (syntax)
	       followed by zero or more ``sem'' lines      (semantics)
	       followed by zero or more ``con'' lines      (constant)

	       A shape line begins with ``SHAPE:'' followed by one of
	    
                  ROUND, SQUARE, RECT, RECT_R, RECT_C, OVAL,
		  DIAMOND, BFR, BFS, TRIANGLE, OCTAGON, 
		  OVAL_H, HEXAGON_L,
		  R_THERMAL, S_THERMAL, SR_THERMAL,
		  HEXAGON_S, DONUT_R, DONUT_S,
		  MOIRE,
		  SPECIAL,
		  NONE
		  
	       A ``syn'' line describes how a particular shape looks in a
	       customer wheel file.  It also may contain the matching between
	       numbers and their meaning.  It begins with ``syn:'' and is 
	       followed by a run of the following:

	       <INT>                 # positive integer              ([0-9]+)
	       <INTk>                # positive integer of length exactly k
	                             # where k is a digit from 1 to 9
	       <FLOAT>               # positive floting point number
	       <ALPHA>               # alphabetic string             ([A-Za-z]+)
	       <CHAR>                # any one character             (.)
	       <ANY>                 # any non-numeric string        ([^0-9]*)
	       <STR>                 # any string without whitespace ([^ \t]+)
	                             # (like %s of scanf())
	       <NL>                  # new line                      ($)
	       <VBAR>                # Vertical bar, ``|''
	       <PARENTHESISED>       # any parenthesized string not containing
	                             # closed parentheses
	       <"string">            # string w/o quotation marks
	       <"string1|string2">   # A possibility of one of two strings
	                             # with more than one ``|'' allowed
	       <_____=A>             # Any of the above followed by a
	                             # single letter variable [A-J]
				     # Normally used for <INT=A>, <FLOAT=D>,...
				     # and for designating names of SPECIAL's
	       <INT=SIZE>            # any size or ROTATION except STYLE
	       <INTk=WIDTH>          # any size or ROTATION except STYLE
	       <FLOAT=WIDTH>         # any size or ROTATION except STYLE
	       <b>                   # blank                         ([ \t]+)
	       <_____?>              # Any of the above followed by ``?''
	       <INT=DCODE>           # An integer which is the dcode
	       <INTk=DCODE>          # A fixed length integer dcode
				     # meaning that presence is optional.
	                             # Note: In case NUMBERING=STATION,
				     #       The integer is the station number
               string                # Any string not containing quotation
	                             # marks or OPEN_CHAR (``<'')
				     
	       The NONE shape is a special case.  It indicates that no
	       aperture is to be translated in the syn line is matched.
				   
	       e.g.
	          
                  syn:FLASH D<INT=DCODE> <b> RECT <b> <FLOAT=D>, <b> <FLOAT=E>
		  
		  would match the line:
		  
		  FLASH D12 RECT    40.00, 30
		  
		  shape:NONE
		  ##########
		  syn:D<INT> <b> UNUSED
	       
               A ``sem''line completes the semantics of the shape description
	       if neccesary.  ``sem'' record is required when:
	       
	          1. The units of a size are different from the rest of the file
		  2. A number is used to mean two things (rare)

		  
	       A ``sem'' record is also recommended in order to shorten ``syn''
	       records when they become too long.
	       
	       A ``sem'' record begins with ``sem:'' and is followed by
	       one or more of the following seperated by semicolons (``;'')
	       
	       <letter>=<size>
	       <letter>=<size>(UNITS= <units>)
	       <letter>=<size>(UNITS= <coefficient> <units>)
	       <letter>=<size>(UNITS= <coefficient><+/-><constant> <units>)
	       
	       where <letter> is a letter which appears on the right side of
	       an equal sign in the preceding ``syn'' record.
	       <size> is one of the sizes which appears in Appendix A
	       <units> is INCH, MIL, or MM.
	       <coefficient> is an unsigned constant to multiply the value by.
               <+/-><constant> is a constant to add/subtract from the value
	                       read from the wheel file
	       Examples:

	          sem:A=WIDTH                     
		  sem:B=WIDTH(UNITS=MIL);C=HEIGHT
		  sem:C=WIDTH(UNITS=0.1 MIL)
		  sem:D=ANGLE(UNITS=90 DEGREE)
		  sem:D=ANGLE(UNITS=1+90 DEGREE)
		  sem:E=ROTATION(UNITS=DEGREE)
		  sem:F=DCODE
		  
	       A ``con'' line is required in the case that one of the sizes
	       of an aperture does not appear in the wheel file and takes on
	       a constant value.  This most often occurs in thermal apertures.
	       The same size may appear in the ``syn'' or ``sem'' lines as
	       appears in a ``con'' line.  This indicates that if the size
	       does not appear in the file (the question marked number does
	       not appear) that the constant value is to be used.
	       
	       e.g.

	          con:SPOKES=4
		  con:ANGLE=45 DEGREES
                  con:STYLE=ROUND
                  con:NAME=moire20

	        Special symbols may have a NAME attibute (which appears
	        in a ``con'' line) to map an aperature to special symbol
	        previously input into the GENESIS 2000 database.
	        This name attribute can include letters defined in the
	        ``syn'' line surrounded with OPEN_CHAR and CLOSE_CHAR
		(usually <>), and will be replaced by the values received by
		these letters.
		     
		 e.g.
		    SHAPE:SPECIAL
		    #############
		    syn:D<INT=DCODE> <b> ISO-<ALPHA=A> <b> <INT=B>
		    con:NAME=iso<A>_<B>
			
		    on input:
		    D34 ISO-BFF 55
			
		    will become the symbol:
		    iso_bff_55
		  
	       Possible values of ``STYLE'':
	          ROUND, SQUARE, ORTHOGONAL
		  
	       What sizes belong to what symbols?
	      
	          The following tables shows the sizes needed for each symbol.

		  
          | SIZE | WIDTH | HEIGHT | R | OSIZE | ISIZE | WIDTH2 | HEIGHT2
----------+------+-------+--------+---+-------+-------+--------+--------
BFS       |   X  |       |        |   |       |       |        |
ROUND     |   X  |       |        |   |       |       |        |
SQUARE    |   X  |       |        |   |       |       |        |
RECT      |      |   X   |   X    |   |       |       |        |
RECT_R    |      |   X   |   X    | X |       |       |        |
RECT_R    |      |   X   |   X    |   |       |       |   X    |    X
RECT_C    |      |   X   |   X    | X |       |       |        |
OVAL      |      |   X   |   X    |   |       |       |        |
DIAMOND   |      |   X   |   X    |   |       |       |        |
OCTAGON   |      |   X   |   X    | X |       |       |        |
DONUT_R   |      |       |        |   |  X    |  X    |        |
DONUT_R   |      |   X   |        |   |  X    |       |        |
DONUT_S   |      |   X   |        |   |  X    |       |        |
DONUT_S   |      |       |        |   |  X    |  X    |        |
HEXAGON_L |      |   X   |   X    | X |       |       |        |
HEXAGON_S |      |   X   |   X    | X |       |       |        |
MOIRE     |      |   X   |   X    |   |       |       |   X    |
----------+------+-------+--------+---+-------+-------+--------+--------

          |WIDTH|HEIGHT|OSIZE|ISIZE|DIAM|BASE|LEN|ANGLE|SPOKES|  GAP    |STYLE|
----------+-----+------+-----+-----+----+----+---+-----+------+---------+-----+
BFR       |     |      |     |     | X  |    |   |     |      |         |     |
TRIANGLE  |     |  X   |     |     |    | X  |   |     |      |         |     |
OVAL_H    |     |      |     |     | X  |    | X |     |      |         |     |
*_THERMAL |     |      |  X  |  X  |    |    |   |  X  |   X  |   X     |  X  |
*_THERMAL |  X  |      |  X  |     |    |    |   |  X  |   X  |   X     |  X  |
*_THERMAL |  X  |      |     |  X  |    |    |   |  X  |   X  |   X     |  X  |
----------+-----+------+-----+-----+----+----+---+-----+------+---------+-----+

          |WIDTH|HEIGHT|   WIDTH2  |DIAM|BASE|LEN|ANGLE|SPOKES|   GAP   |STYLE|
----------+-----+------+-----+-----+----+----+---+-----+------+---------+-----+
MOIRE     |  X  |  X   |     X     |    |    |   |  X  |   X  |   X     |     |
----------+-----+------+-----+-----+----+----+---+-----+------+---------+-----+


                  Notes: The original table has been split into three for 
		         reasons of compactness and readability.

                         Where a shape appears twice, it is an indication that
                         there is a choice as to which sizes may be present.
			 
			 ``*_THERMAL'' refers to R_THERMAL, S_THERMAL, and 
			 SR_THERMAL.
			 Allowed styles of thermals:
			 
			            | ROUND  |  SQUARE    | ORTHOGONAL |
			 -----------+--------+------------+------------+
			 R_THERMAL  |   X    |     X      |            |
			 S_THERMAL  |        |     X      |      X     |
			 SR_THERMAL |        |     X      |            |
			 -----------+--------+------------+------------+
			 			 
			 The names of moire sizes is rather obscure:
			 WIDTH     - the width of each ring
			 HEIGHT    - the length of the cross
			 WIDTH2    - the width of the cross
			 ANGLE     - the angle of the cross
			 SPOKES    - the number of rings
			 GAP       - the distance between rings

		  In addition:
		  1. Every symbol may have a ROTATION value of 0,90,180 or 270.

              Conventions :

	         1. A line of sharps appears between the ``SHAPE'' line 
		    and the ``syn'' line

                    e.g.

                       SHAPE:RECT
		       ###################
		       syn:<INT=DCODE> <b> RECT <b> <INT=D> <CHAR> <INT=E> 
		       sem:WIDTH=D;HEIGHT=E;

                 2. A blank row appears between shapes.

                 3. The file is in uppercase except for:
                    A. ``syn'', ``sem''
                    B. ``<b>''
                    C. The names of special symbols
		    
		 4. Wheel templates are named according to the order that the
		    following fields appear in the wheel file.
		    
		    DCODE   - the dcode of the aperture
		    NAME    - the name of the aperture (e.g. CIRCLE, RECT)
		    SIZE    - the size of the aperture (e.g. WIDTH, HEIGHT)
		    ORDINAL - the ordinal value in the aperture table.
		    
		    The first letter of each of these words is taken in the
		    order that the appropriate value appears in the wheel
		    file.  If the value does not appear the letter is omitted.
		    
		    This is followed by the maximal number of records per line
		    if this value is greater than one.
		    
		    This is followed by a dot, and the ordinal of the wheel
		    that has the same name up to this point.
		    
		    This naming convention is intended to stop the user from
		    drowning in a sea of growing wheel templates.
		    
		    e.g.
		    
		       A wheel with lines of this kind:
		    
		       DCODE 10  CIRCLE 43.0
		       
		       would be called dns.5 if it was the fifth ``dns''
		       
		    e.g.
		    
		       A wheel with lines of this kind:
		    
		       1. D4 43.0 ROUND
		       
		       would be called odns.3 if it was the third ``odns''
		       
		    e.g.
		    
		       A wheel with records of this kind:
		    
		       D4 RECT 25.0 50.0          D5 SQUARE 43.0 
		       
		       would be called dns2.1 if it was the first ``dns2''
		   
	      Suggestions :
	         1. Avoid use of <ANY> when possible, by explicitly writing
		    what must appear.  Indiscriminate use of <ANY>  
		    can cause false identification of files
		    which are not of the same format.
		    
              Notes :
	         1. It is not possible to use the `program' file
		    for preprocessing before applying a wheel template.
		    If there is a need for pre-processing, in order to overcome
		    limitations of the wheel template mechanism, then
		    this preprocessing may be done offline.
		 
	      Caveats :
	  
	         I often made the following errors when writing
		 wheel templates.
		   
		 1. Forgetting to put in ``<b>'' where there are blanks 
		 2. Quoting text outside of <>.
		 
