home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 403.lha / HamLab_v1.0Demo / HamLab.doc < prev    next >
Encoding:
Text File  |  1990-07-26  |  9.0 KB  |  247 lines
  1. HamLab Version 1.0 DEMO
  2. (c) Copyright 1990 J. Edward Hanway
  3.  
  4. Permission is hereby granted to redistribute and use the demo version of
  5. HamLab, including the GIF, Spectrum 512 and MTV filters, provided that the
  6. distribution is complete and unmodified.
  7.  
  8. There is no warranty on this program.  I disclaim any responsibility for
  9. any damages that it may cause, direct or coincidental.
  10.  
  11. This is a "demo" version, which will crop any image larger than 512 pixels
  12. wide or tall.  Other than that, all features of the "real" program are
  13. enabled.  To register and and receive a complete working version, the
  14. latest set of input filters, and example filter source code, send
  15. $15.00 (US) to:
  16.  
  17.     J. E. Hanway
  18.     149 Scotch Pine Dr.
  19.     Rochester, NY 14616-1668
  20.  
  21. The HamLab demo includes:
  22.  
  23.     HamLab_demo    --    the program
  24.     HamLab_demo.info --    its icon
  25.     HamLab.readme    --    short "what is this?" file
  26.     HamLab.doc    --    you're reading it
  27.     HamLab.config    --    example configuration file
  28.     GIF2hl        --    GIF to HamLab filter
  29.     spec2hl        --    Spectrum 512 to HamLab filter
  30.     MTV2hl        --    MTV ray tracer to HamLab filter
  31.  
  32. OVERVIEW
  33.  
  34.     The purpose of HamLab is to read "foreign" images, especially those
  35.     created for high-resolution, deep-bitmap displays, and convert them
  36.     to Amiga Hold-and-Modify (HAM) images, while trying to preserve as
  37.     much of the original's quality as possible.  The HAM images can be
  38.     displayed (on a large "virtual screen" if necessary) and saved as
  39.     IFF files, suitable for use with a HAM paint program like NewTek's
  40.     DigiPaint.
  41.  
  42. SYSTEM REQUIREMENTS
  43.  
  44.     REQUIRED
  45.  
  46.     AmigaDOS 1.3 or later (has been briefly tested with 2.0 beta 5)
  47.  
  48.     ARP 1.3 (for its file requester and its multiple process support;
  49.     only LIBS:arp.library (17100 bytes) is required)
  50.  
  51.     RECOMMENDED
  52.  
  53.     PIPE: device (comes with AmigaDOS 1.3; needed only if the
  54.     "Use Pipes" option is used)
  55.         
  56.     HamLab runs on a 68000, a 68030, and likely everything in between.
  57.     
  58. HAMLAB COMMANDS
  59.  
  60.     OPEN        (shortcut: 'o')
  61.  
  62.     This command brings up the ARP file requester and allows you to
  63.     open a new image file.  HamLab tries to identify the file according
  64.     to its configuration information, and if it can be identified, the
  65.     appropriate input filter will be run and the image will be converted
  66.     to a 24-bit RGB    temporary file. (If the "Use Pipes" option is
  67.     selected, then a temporary file won't be created. Instead, a pipe
  68.     will be opened and part of what is normally the READ command will be
  69.     executed using the data coming through the pipe.  See below for more
  70.     information on using pipes.)
  71.  
  72.     READ        (shortcut: 'r')
  73.  
  74.     This command reads the 24-bit temporary file and does the necessary
  75.     calculations to fit it to the Amiga's 4096 color palette
  76.     (quantizing), then picks 16 colors to use in HAM mode to minimize
  77.     HAM fringing artifacts (analyzing). Depending on how you set the
  78.     "Cache12Bit" option in the configuration file (see below) the
  79.     resulting picture will either be held in RAM or in another
  80.     temporary file.
  81.  
  82.     DISPLAY        (shortcut: 'd')
  83.  
  84.     This command opens an intuition HAM screen and renders the picture
  85.     into it.  If your Workbench screen is overscanned, this screen will
  86.     be, too.  If the image that you're converting is larger than the
  87.     screen size, then you can pan around the image using the arrow keys
  88.     or by holding down the left mouse button and dragging.  The right
  89.     mouse button or space bar will close the display screen.  (Other
  90.     shortcut keys still work, too.)
  91.     
  92.     SAVE        (shortcut: 's')
  93.  
  94.     This selection brings up the ARP file requester and allows you to
  95.     save the image as an IFF HAM file.
  96.  
  97.     You need not display an image before saving it.  However, doing so
  98.     will make the save process slightly faster.
  99.  
  100.     ABORT        (shortcut: 'a')
  101.  
  102.     This selection allows you to abort any lengthy process.
  103.  
  104.     CLOSE        (shortcut: 'q')
  105.  
  106.     Clicking the close gadget of the HamLab window exits the program.
  107.  
  108. OPTIONS
  109.  
  110.     USE PIPES    (shortcut: 'p')
  111.  
  112.     When this option is enabled, the next time you OPEN a file, rather
  113.     than creating a huge temporary 24 bit RGB file, the image will be
  114.     piped directly through part of the READ command using the AmigaDOS
  115.     1.3 PIPE: device. Although this saves a lot of temporary file space
  116.     and gets the conversion    done faster than going to a temporary file,
  117.     even in in RAM:, it does mean that if you need to re-analyze an
  118.     image (like after you turn dithering on or off), the image must be
  119.     re-opened and converted from its original format all over again.
  120.  
  121.     INTERLACE    (shortcut: 'i')
  122.  
  123.     When this option is enabled, the HAM image will be interlaced.
  124.     The image size is not changed.  Toggling this option does not
  125.     require any recalculations.
  126.  
  127.     HORIZ SQUEEZE    (shortcut: 'h')
  128.  
  129.     When this option is enabled, the width of the original image will
  130.     be cut in half. Using this option in combination with the INTERLACE
  131.     option allows 640x480 VGA pictures to be converted to interlaced
  132.     320x480    HAM pictures. (NOTE: in the demo version, the image will be
  133.     cropped    at 512 pixels as it is read in, so the HAM picture will only
  134.     be 256 pixels wide.) After toggling this option, the image must be
  135.     re-read.
  136.  
  137.     F-S DITHER    (shortcut: 'f')
  138.  
  139.     If this option is enabled, whenever the file is fit into the Amiga's
  140.     4096 color palette, a "Boustrophedonic Floyd-Steinberg Error
  141.     Diffusion" step    is performed.  This is a pretentious way to say
  142.     that the HAM image will be dithered so that any colors which don't
  143.     have exact matches in the Amiga's palette will be displayed by
  144.     alternating between similar colors so that the average over a large
  145.     area approximates the original color.
  146.  
  147.     Using this option significantly improves the results when converting
  148.     images which began life on a system with a larger color palette,
  149.     such as the 262,144 color palette used by the VGA and the 16.7
  150.     million    color palette of many 8-bit and    24-bit systems.    In
  151.     particular, it helps eliminate "banding," an artifact where a
  152.     gradual color change results in several sharp-edged bands of color.
  153.     (This happens a lot in soft shadows.)
  154.  
  155.     After toggling this option, the image must be re-read.
  156.  
  157.     FAST ANALYZE    (shortcut: 'z')
  158.  
  159.     This option affects how HamLab chooses the 16 color palette used to
  160.     minimize HAM fringing artifacts.  When disabled, HamLab analyzes
  161.     the picture separately for each of the 16 colors, each time picking
  162.     the one    which helps the most.  When enabled, HamLab only analyzes
  163.     the picture once and then picks all 16 colors.  Although the slow
  164.     analysis should, in theory, be better, in practice, I notice little
  165.     or no difference in quality between the two methods, and the fast
  166.     analysis is 16 times as fast.
  167.  
  168.     After toggling this option, the image must be re-read, but the
  169.     24-bit to 12-bit quantization will not be recomputed unless changing
  170.     one of the other options necessitates it.
  171.  
  172. CONFIGURATION FILE
  173.  
  174. The HamLab configuration file is a text file which HamLab uses to determine
  175. what input filters it has available, as well as other miscellaneous
  176. configuration options. HamLab looks for the configuration file in the
  177. following places, in order:
  178.  
  179.     HamLab.config    (in the current directory)
  180.     DEVS:HamLab.config
  181.     S:HamLab.config
  182.  
  183.  
  184. Lines in the configutation file must be in one of the following formats. A
  185. '#' denotes that the rest of the line is a comment.
  186.  
  187. FilterPath    "disk path"
  188.  
  189.     Specifies the disk path where the filter programs can be found.
  190.  
  191. TempPath    "disk path"
  192.  
  193.     Specifies the disk path where any temporary file(s) will be created.
  194.  
  195. InPath        "disk path"
  196. OutPath        "disk path"
  197.  
  198.     These set the initial directories for the input and output file
  199.     requesters. (Of course, you can read and write from/to any
  200.     directory; these are just for convenience.)
  201.  
  202. UsePipes    0/1
  203. FastAnalyze    0/1
  204. Interlace    0/1
  205. HSqueeze    0/1
  206.  
  207.     These (optional) lines specify the initial values for HamLab's
  208.     options.
  209.  
  210. Cache12Bit    size (32 bit signed value)
  211.  
  212.     This specifies the maximum size, in bytes, of HamLab's 12-bit
  213.     temporary data that will be kept in RAM. If an image requires more
  214.     room than this value, it will be kept in a temporary file. Some
  215.     useful values to use here are:
  216.         0    -- always use a file
  217.         -1    -- always keep it in memory
  218.         130000    -- keep 320 x 200 and smaller in RAM
  219.  
  220. Filter        "matchstring" "filtername"
  221.  
  222.     One of these lines must be present for every input filter. The first
  223.     string is the pattern which identifies that type of file. The
  224.     second is the name of the filter program.
  225.  
  226. SUGGESTED CONFIGURATIONS:
  227.  
  228.     If you've got memory to burn, leave UsePipes turned off, set
  229.     TempPath to RAM: and set Cache12Bit to -1. This will keep both
  230.     24-bit and 12-bit temporary images in memory.  Beware, though,
  231.     a 640 x 480 image will take up about 1.5 MEGS just in temporary
  232.     files.
  233.  
  234.     HamLab and its input filters are "pure" code, so they can be made
  235.     resident if you so desire.
  236.  
  237.     If you're short on memory, turn UsePipes on, set TempPath to a disk
  238.     directory (a hard disk is nice, but not necessary) and set
  239.     Cache12Bit to something low, like 0.  This will eliminate the 24
  240.     bit file and keep the 12-bit temporary file on disk.  If you then
  241.     save a picture without displaying it first, then HamLab will only
  242.     need a few lines of the picture in memory at a time.
  243.  
  244.     Displaying the picture is the only thing that requires any significant
  245.     amounts of CHIP RAM. Note that a 640 x 480 HAM image takes about 230K
  246.     of CHIP ram, though not all contiguous.
  247.