home *** CD-ROM | disk | FTP | other *** search
/ Graphics 16,000 / graphics-16000.iso / msdos / utils / fbm2fl03.lha / fboctree.doc < prev    next >
Text File  |  1993-11-16  |  9KB  |  189 lines
  1. ===========================================================================
  2. /* fboctree.doc */
  3.  
  4. Copyright (C) 1993 by Klaus Ehrenfried. 
  5.  
  6. Permission to use, copy, modify, and distribute this software
  7. is hereby granted, provided that the above copyright notice appears 
  8. in all copies and that the software is available to all free of charge. 
  9. The author disclaims all warranties with regard to this software, 
  10. including all implied warranties of merchant-ability and fitness. 
  11. The code is simply distributed as it is.
  12.  
  13. ===========================================================================
  14.  
  15. About FBOCTREE:
  16.  
  17. The program `fboctree' allows to quantize a 24 bit color image to 
  18. a mapped image. The program uses the Octree algorithm described 
  19. by Michael Gervautz and Werner Purgathofer (Technical University 
  20. Vienna, Austria) in the article "A Simple Method for Color Quantization:
  21. Octree Quantization" published in Graphic Gems edited by Andrew Glassner
  22. pp. 287 ff. The program allows to quantize single images and series 
  23. of images as well. A series of images can be quantized so that all 
  24. resulting mapped images have the same color table which is evaluated 
  25. to fit the used colors of the complete series. This is useful when 
  26. the images should later be animated, e.g. with the program `fbm2fli'. 
  27. `fboctree' uses the library of the FBM package to read and write 
  28. the images. Thus is can handle various file formats.
  29.  
  30. ===========================================================================
  31.  
  32. Usage:
  33.   fboctree -s [-c<numcolors>] [-d<bits>] [-<type>] < rgb > mapped
  34.   fboctree -a [-c<numcolors>] octree < rgb
  35.   fboctree [-d<bits>] [-<type>] octree < rgb > mapped
  36.  
  37.   "numcolors" is the number of colors used for the Octree quantization.
  38.   This value can range from 9..256, default is 256.
  39.  
  40.   "bits" is the color depth used in the color map of the output image.
  41.   This value can range from 2..8, default is 8.
  42.  
  43.   "type" indicates the format of the output file. Here are few of the 
  44.   available formats (for a complete list see the description in the 
  45.   FBM package): 'F' =  FBM, 'G' =  GIF, 'S' =  Sun-Raster, 'Z':  PCX.
  46.   Default type is FBM.
  47.     
  48.   "octree" is the name of the file which contains the Octree data.
  49.   The Octree data is the information about color distribution in the 
  50.   scanned input images. This information determines the color table 
  51.   of the mapped output images. 
  52.  
  53.   "rgb" is the not mapped input file (e.g. 24 bit FBM image).
  54.  
  55.   "mapped" is the mapped output file (8 bits/pixel; max. 256 colors).
  56.  
  57. The program can be used in three different modes:
  58.  
  59. 1) The "-s" option indicates "single" mode. A single 24 bit image 
  60.    is converted to a single mapped image. 
  61.    Example:
  62.       fboctree -s -G -c128 < abc24.fbm.Z > abc.gif
  63.  
  64.    Reads the 24 bit compressed FBM image "abc24.fbm.Z", quantizes it 
  65.    and writes a GIF output image "abc.gif". Due to the given "-c128"
  66.    only 128 colors are used in the color-map of the GIF file. 
  67.    Note: The read filter of the FBM package automatically detects that 
  68.    the input file is compressed. 
  69.  
  70. 2) The "-a" option indicates "add" mode. A single 24 bit image is 
  71.    scanned and it's color information is added to the Octree which 
  72.    is read from the file given in the command line. Then the modified 
  73.    Octree is written back to the file. Thereby the old information 
  74.    in the Octree file is overwritten. If the given Octree file doesn't 
  75.    exist a new Octree is generated. Only in this case the "-c" option 
  76.    is effective which determines the number of colors used for the 
  77.    Octree. 
  78.    Example:
  79.       uncompress < abc24.qrt.Z | qrt2fbm | fboctree -a octree.data
  80.  
  81.    "abc24.qrt.Z" is a compressed QRT image generated by the POV or 
  82.    DKB ray-tracer. This QRT image is read by "uncompress" and piped 
  83.    through the `qrt2fbm' filter from the FBM package which converts 
  84.    the image to the FBM format. Then `fboctree' reads the pixel values
  85.    and uses this information to update the Octree which is stored in 
  86.    the file "octree.data". Note: The internal read filter of the FBM 
  87.    package can't handle the QRT format directly, so that this way with 
  88.    the additional external filter `qrt2fbm' is used. The QRT file 
  89.    can be kept compressed to save disk space. 
  90.  
  91. 3) Without "-s" and "-a" one gets the simple quantization mode. A single 
  92.    24 bit image is read and the information of the given Octree is 
  93.    used to quantize the image to a mapped image. 
  94.    Example:
  95.       fboctree -S octree.data < abc24.fbm.Z | compress > abc.rs.Z
  96.  
  97.    The FBM image "abc24.fbm.Z" is quantized and the output is passed 
  98.    in SUN raster format via a pipe to the `compress' command which 
  99.    finally writes the resulting image to the file "abc8.rs.Z". 
  100.    The Octree which is used for the quantization is taken from 
  101.    the file "octree.data". The Octree file remains unchanged. 
  102.  
  103. ===========================================================================
  104.  
  105. Animation (FBOCTREE and FBM2FLI):
  106.  
  107.    Assuming one has 100 QRT images generated by the POV or DKB ray-tracer 
  108.    and he or she wants to animate the 100 images in a FLI animation. 
  109.    The images are named "nice00.qrt.Z", "nice01.qrt.Z" ... "nice99.qrt.Z".
  110.    All are compressed to save disk space. First step is to generate 
  111.    an Octree which represents the color information of all 100 images. 
  112.    As name for the Octree file we chose "octree100.data". This file 
  113.    doesn't exist at the beginning. Then the Octree is generated with 
  114.    the following commands:
  115.  
  116.    uncompress < nice00.qrt.Z | qrt2fbm | fboctree -a octree100.data
  117.    uncompress < nice01.qrt.Z | qrt2fbm | fboctree -a octree100.data
  118.                                   :
  119.                                   :
  120.    uncompress < nice99.qrt.Z | qrt2fbm | fboctree -a octree100.data
  121.  
  122.    Now all images are scanned and the Octree (and thereby the color table) 
  123.    is ready. The hole information is stored in the file "octree100.data". 
  124.    In the second step follows the quantization. To store the mapped 
  125.    images we chose the GIF format. The quantization is done with the 
  126.    commands:
  127.  
  128.    uncompress < nice00.qrt.Z | qrt2fbm | fboctree -G octree100.data > m00.gif
  129.    uncompress < nice01.qrt.Z | qrt2fbm | fboctree -G octree100.data > m01.gif
  130.                                   :
  131.                                   :
  132.    uncompress < nice99.qrt.Z | qrt2fbm | fboctree -G octree100.data > m99.gif
  133.  
  134.    Now we have a series of GIF images with the names "m00.gif" ... "m99.gif".
  135.    To use the `fbm2fli' program we generate a list file by:
  136.  
  137.    ls -1 m*.gif > allgif.list
  138.  
  139.    Thereby we have assumed that no other files in the directory match 
  140.    the template "m*.gif". Finally the animation can be done by:
  141.  
  142.    fbm2fli allgif.list anim100.fli
  143.  
  144.    The complete way to get a FLI animation from QRT images seems to be 
  145.    rather complicated especially in comparison to the MS DOS program DTA. 
  146.    This is definitely true, but the complicated way offers on the 
  147.    other hand more flexibility. We can handle more file formats and the
  148.    `fboctree' program is more consistent with the other utilities of the
  149.    FBM package like `fbquant'.
  150.  
  151. ===========================================================================
  152.  
  153. FBOCTREE vs FBQUANT:
  154.  
  155.    The program `fbquant' is the quantization program of the FBM package.
  156.    In principle it does the same what `fboctree' does, but it uses a 
  157.    different algorithm, namely a variant of Heckbert's adaptive partitioning
  158.    method. Additionally Floyd-Steinberg dithering is used to reduce color 
  159.    banding (Note: The automatic dithering of `fbquant' can be avoided by 
  160.    specifying the "-n" option, although this possibility is not mentioned
  161.    in the man page for `fbquant'). Basically the algorithm used by `fbquant' 
  162.    gives better results than the Octree method, but is has some disadvantages, 
  163.    if a FLI animation with the resulting mapped images is planned. 
  164.    The dithering improves the quality of the mapped images significantly
  165.    but the resulting images are less suitable for the use in FLI animations. 
  166.    If dithered images are used, the resulting FLI file is much bigger than in 
  167.    the case where the images are not dithered. This results from the special 
  168.    compression method used in the FLI standard. 
  169.    If the size of the resulting FLI file or the animation speed is a critical 
  170.    point, the quantization method with `fboctree' as described above has 
  171.    to be preferred. 
  172.  
  173. ===========================================================================
  174.  
  175. Installation:
  176.  
  177.    Like the program `fbm2fli' also `fboctree' requires the library of the 
  178.    FBM package from Michael Mauldin (mlm@nl.cs.cmu.edu).
  179.    This package is available via FTP as
  180.  
  181.         "nl.cs.cmu.edu:/usr/mlm/ftp/fbm.tar.Z".
  182.  
  183.    Probably some changes in the makefile are required to indicate 
  184.    where the FBM stuff is located on your machine and which compiler 
  185.    is used. 
  186.  
  187. -- Klaus Ehrenfried (klaus@spock.es.go.dlr.de)
  188.  
  189.