





                              DTGA  Documentation
                                 Version 3.0




                                   CONTENTS  

   1.0  DISCLAIMER AND LICENSE STATEMENTS, ETC.
   2.0  SYSTEM REQUIREMENTS.
   3.0  LIST OF FILES.
   4.0  INTRODUCTION.
   5.0  USING DTGA.
   5.1  COMMAND LINE OPTIONS.
   

   1.0 DISCLAIMER AND LICENSE STATEMENTS, ETC.

   If you don't agree to BOTH the DISCLAIMER OF  WARRANTY  and  LICENSE  
   AGREEMENT statements, please don't use this program.  

   -------------------------------------------------------------------------
                             DISCLAIMER OF WARRANTY
   -------------------------------------------------------------------------   


   THIS SOFTWARE PROGRAM AND DOCUMENTATION ARE PROVIDED "AS IS" AND WITHOUT 
   WARRANTIES AS TO PERFORMANCE.  

   THE PROGRAM DTGA IS PROVIDED WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES 
   WHATSOEVER.  BECAUSE OF THE DIVERSITY OF CONDITIONS AND HARDWARE UNDER
   WHICH THE PROGRAM MAY BE USED, NO WARRANTY OF FITNESS FOR A PARTICULAR
   PURPOSE IS OFFERED.  THE USER IS ADVISED TO TEST THE PROGRAM THOROUGHLY
   BEFORE RELYING ON IT.  THE USER MUST ASSUME THE ENTIRE RISK OF USING THIS
   PROGRAM.  
  

   -------------------------------------------------------------------------
                               LICENSE  AGREEMENT
   -------------------------------------------------------------------------   

   
    You are granted a non-exclusive license to use the program and source code.

   

   -------------------------------------------------------------------------
                                    SUPPORT
   -------------------------------------------------------------------------

   I want to hear from you!  I can be reached by electronic mail:

           Compuserve  (76356,741)

      My US mailing address is:

             Robert M. Crawford
             1075 Elsie Mae Drive
             Boulder Creek, CA 95006 



   -------------------------------------------------------------------------   
                          CREDITS  AND  TRADEMARKS
   -------------------------------------------------------------------------   


    IBM is a registered trademark of International Business Machines, Corp.  
      
    GIF and 'Graphics Interchange Format' are trademarks (tm) of Compuserve
    Incorporated, an H&R Block Company.



   2.  SYSTEM REQUIREMENTS.

   DTGA runs on IBM PC, XT, AT, PS/2 (or clone) computers, with 512K of RAM, 
   and DOS 2.0 or higher. 


   3.  LIST OF FILES.

             File             Description

             README.1ST       Disclaimer of Warranty Statement.
             DTGA.TXT         Software Documentation (this file).
             DTGA.EXE         Targa-24 to 256-color GIF Conversion Program.
             DTGASRC.ZIP      DTGA source code.

   4.  INTRODUCTION.  

   I developed DTGA to see how my "tetrahedron partitioning" dither algorithm
   works with 24-bit to 256-color reduction.  DTGA converts uncompressed 
   Targa-24 files to 256-color GIF files.  I've been able to get some pretty 
   good results, although sometimes I've had to fiddle with the command line 
   parameters to get it.  

   The algorithm I'm using initially splits the color cube into 27 subcubes.
   Each subcube is split into 6 tetrahedrons (162 total) .  This initial state 
   requires 64 colors.  Next, a color histogram is built up from the image.
   The algorithm keeps spliting the tetrahedron enclosing the pixels with
   the largest weighted error until all the colors are exhausted or a minimum
   error level is met.

     
   5.   USING DTGA.

   DTGA uses a command line interface. The general syntax is:

                dtga [options] source [destination]

   Command line parameters must be separated by at least one space. No 
   spaces are allowed within a parameter.  

   Source is the TGA file to be . The file name may include the 
   full path name.   If source does not have an extension .TGA is assumed.

   Destination is the outout GIF file name.  If destination doesn't have an 
   extention, GIF is assumed.  If it isn't included in the command line the 
   source file name is used but with the .GIF extention.  

   Command line options are, of course, optional.   More than one option can 
   be specified.  A  summary of command line options can be displayed by 
   executing DGIF without parameters.  



   5.1  COMMAND LINE OPTIONS.


   --------------------------------------------------------------------------
   -a                    Set Color Distibution
   --------------------------------------------------------------------------
   This option allows a parameter to be set that controls the distribution
   of colors in the output image.  High values increase the number of dark
   colors in the image.  The default value is 100.  Valid values are from
   50 to 400.

   Example:

           dtga -a200 image  , increase the number of dark colors.

   --------------------------------------------------------------------------
   -cd,-cl               Set Contast Limits
   --------------------------------------------------------------------------
   These options allows the image contrast to be adjusted.  Option -cd controls
   the "dark limit" and option -cl controls the "lite limit".  Valid values
   for the "dark limit" are 0 to 64 (default = 0).  Valid values for the  
   lite limit are 191 to 255 (default = 255).

   Example:

           dtga -cd8 - cl239 image  , RGB component values are set to 0 if less
                                      than 8. Values greater than 239 are set
                                      to 255. Values between 8 and 239 are
                                      spread evenly between 0 and 255.

   --------------------------------------------------------------------------
   -d             Disable Use of Color Look-Up Table
   --------------------------------------------------------------------------
   By default DTGA builds up and uses a look-up table to speed up color 
   selection.  If this option is used, the look-up table will not be used.
   I included this option to see if the look-up table quantitization would
   effect the output image (I haven't been able to tell the difference).

   --------------------------------------------------------------------------
   -r,-g,-b          RGB Color Histogram  Quantitization
   --------------------------------------------------------------------------
   The color histogram is limited to 8000 entries, so the rgb colors have to
   be quantized. By default DTA quantizes red and blue to 5-bits (3-bits 
   discarded) and green to six bits (2-bits discarded) .  Using these values, 
   the histogram may sometimes overflow (no new color are added).  These 
   options allow you to increase the quantitization to prevent overflow.  You
   can also reduce the quantitization to increase the number of colors in the
   histogram. 

   Example:

           dtga -g3 image  

   --------------------------------------------------------------------------
   -o                         Output Gamma
   --------------------------------------------------------------------------
   This option allows the output gamma to be adjusted.  The default value is
   2.0.   Gamma values can range between 10 (1.0) and 40 (4.0).

   Example:

           dtga -o22 image   , set output gamma to 2.2.


   --------------------------------------------------------------------------  
   -e                         Minimum Error
   --------------------------------------------------------------------------
   This option lets you change the error level used to determine if a 
   hetrahedron should be split.  The default value is 20.  Valid values
   are from 8 (smallest error) to 50.

   Example:

           dtga -e30 image   

   --------------------------------------------------------------------------  
   -f                         Use Fixed Color Table
   --------------------------------------------------------------------------
   This option lets you select a fixed 256 color table which is independant
   of the input image.  The results are sometimes very good.


   Example:

           dtga -f image   


   --------------------------------------------------------------------------
   -i                          Input Gamma 
   --------------------------------------------------------------------------
   This option allows the input gamma to be adjusted. The default value is
   10 (1.0, no correction).  Gamma values can range between 10 (1.0) and
   40 (3.0). 

   Example:

           dtga -i20 image  

   
   --------------------------------------------------------------------------
   -n                         Maximum Colors 
   --------------------------------------------------------------------------
   This option allows the number of output colors to be set. The default value
   is 256.   Valid values are from 64 to 256.

   Example:

           dtga -n128 image   , limit gif image to 128 colors

   --------------------------------------------------------------------------
   -m                         Set Pixel Threshold 
   --------------------------------------------------------------------------
   DTGA uses the number of pixels enclosed by a tetrahedron to decide if the
   tetrahedron can be split.  If the number of pixels is less than a specified
   threshold, the tetrahedron will not be split until all other tetrahedrons
   exceeding the threshold and have weighted errors greater than the error
   limit have been split.  The default value is 50 pixels.

 
   Example:

           dtga -m100 image   , set limit to 100 pixels
  
   --------------------------------------------------------------------------
   -w                         Color Weighting 
   --------------------------------------------------------------------------
   DTGA uses a weighted rgb distance measure when deciding how to split a
   tetrahedron.  The edge with the largest weighted distance is split.
   This option allows you to change the weighting used by DTGA. The default
   values are 2 for red, 3 for green and 1 for blue (-w231). Valid values
   are from 1 to 6 for eace color component.  Also, the sum of the weights is
   limited to 10.

   Example:

           dtga -w111 image   , use equal weighting


   --------------------------------------------------------------------------
   -p                         Internal clipping level 
   --------------------------------------------------------------------------
   This option sets the minimum clipping level, default is 5 percent.



