HamLab Version 1.0 DEMO (c) Copyright 1990 J. Edward Hanway Permission is hereby granted to redistribute and use the demo version of HamLab, including the GIF, Spectrum 512 and MTV filters, provided that the distribution is complete and unmodified. There is no warranty on this program. I disclaim any responsibility for any damages that it may cause, direct or coincidental. This is a "demo" version, which will crop any image larger than 512 pixels wide or tall. Other than that, all features of the "real" program are enabled. To register and and receive a complete working version, the latest set of input filters, and example filter source code, send $15.00 (US) to: J. E. Hanway 149 Scotch Pine Dr. Rochester, NY 14616-1668 The HamLab demo includes: HamLab_demo -- the program HamLab_demo.info -- its icon HamLab.readme -- short "what is this?" file HamLab.doc -- you're reading it HamLab.config -- example configuration file GIF2hl -- GIF to HamLab filter spec2hl -- Spectrum 512 to HamLab filter MTV2hl -- MTV ray tracer to HamLab filter OVERVIEW The purpose of HamLab is to read "foreign" images, especially those created for high-resolution, deep-bitmap displays, and convert them to Amiga Hold-and-Modify (HAM) images, while trying to preserve as much of the original's quality as possible. The HAM images can be displayed (on a large "virtual screen" if necessary) and saved as IFF files, suitable for use with a HAM paint program like NewTek's DigiPaint. SYSTEM REQUIREMENTS REQUIRED AmigaDOS 1.3 or later (has been briefly tested with 2.0 beta 5) ARP 1.3 (for its file requester and its multiple process support; only LIBS:arp.library (17100 bytes) is required) RECOMMENDED PIPE: device (comes with AmigaDOS 1.3; needed only if the "Use Pipes" option is used) HamLab runs on a 68000, a 68030, and likely everything in between. HAMLAB COMMANDS OPEN (shortcut: 'o') This command brings up the ARP file requester and allows you to open a new image file. HamLab tries to identify the file according to its configuration information, and if it can be identified, the appropriate input filter will be run and the image will be converted to a 24-bit RGB temporary file. (If the "Use Pipes" option is selected, then a temporary file won't be created. Instead, a pipe will be opened and part of what is normally the READ command will be executed using the data coming through the pipe. See below for more information on using pipes.) READ (shortcut: 'r') This command reads the 24-bit temporary file and does the necessary calculations to fit it to the Amiga's 4096 color palette (quantizing), then picks 16 colors to use in HAM mode to minimize HAM fringing artifacts (analyzing). Depending on how you set the "Cache12Bit" option in the configuration file (see below) the resulting picture will either be held in RAM or in another temporary file. DISPLAY (shortcut: 'd') This command opens an intuition HAM screen and renders the picture into it. If your Workbench screen is overscanned, this screen will be, too. If the image that you're converting is larger than the screen size, then you can pan around the image using the arrow keys or by holding down the left mouse button and dragging. The right mouse button or space bar will close the display screen. (Other shortcut keys still work, too.) SAVE (shortcut: 's') This selection brings up the ARP file requester and allows you to save the image as an IFF HAM file. You need not display an image before saving it. However, doing so will make the save process slightly faster. ABORT (shortcut: 'a') This selection allows you to abort any lengthy process. CLOSE (shortcut: 'q') Clicking the close gadget of the HamLab window exits the program. OPTIONS USE PIPES (shortcut: 'p') When this option is enabled, the next time you OPEN a file, rather than creating a huge temporary 24 bit RGB file, the image will be piped directly through part of the READ command using the AmigaDOS 1.3 PIPE: device. Although this saves a lot of temporary file space and gets the conversion done faster than going to a temporary file, even in in RAM:, it does mean that if you need to re-analyze an image (like after you turn dithering on or off), the image must be re-opened and converted from its original format all over again. INTERLACE (shortcut: 'i') When this option is enabled, the HAM image will be interlaced. The image size is not changed. Toggling this option does not require any recalculations. HORIZ SQUEEZE (shortcut: 'h') When this option is enabled, the width of the original image will be cut in half. Using this option in combination with the INTERLACE option allows 640x480 VGA pictures to be converted to interlaced 320x480 HAM pictures. (NOTE: in the demo version, the image will be cropped at 512 pixels as it is read in, so the HAM picture will only be 256 pixels wide.) After toggling this option, the image must be re-read. F-S DITHER (shortcut: 'f') If this option is enabled, whenever the file is fit into the Amiga's 4096 color palette, a "Boustrophedonic Floyd-Steinberg Error Diffusion" step is performed. This is a pretentious way to say that the HAM image will be dithered so that any colors which don't have exact matches in the Amiga's palette will be displayed by alternating between similar colors so that the average over a large area approximates the original color. Using this option significantly improves the results when converting images which began life on a system with a larger color palette, such as the 262,144 color palette used by the VGA and the 16.7 million color palette of many 8-bit and 24-bit systems. In particular, it helps eliminate "banding," an artifact where a gradual color change results in several sharp-edged bands of color. (This happens a lot in soft shadows.) After toggling this option, the image must be re-read. FAST ANALYZE (shortcut: 'z') This option affects how HamLab chooses the 16 color palette used to minimize HAM fringing artifacts. When disabled, HamLab analyzes the picture separately for each of the 16 colors, each time picking the one which helps the most. When enabled, HamLab only analyzes the picture once and then picks all 16 colors. Although the slow analysis should, in theory, be better, in practice, I notice little or no difference in quality between the two methods, and the fast analysis is 16 times as fast. After toggling this option, the image must be re-read, but the 24-bit to 12-bit quantization will not be recomputed unless changing one of the other options necessitates it. CONFIGURATION FILE The HamLab configuration file is a text file which HamLab uses to determine what input filters it has available, as well as other miscellaneous configuration options. HamLab looks for the configuration file in the following places, in order: HamLab.config (in the current directory) DEVS:HamLab.config S:HamLab.config Lines in the configutation file must be in one of the following formats. A '#' denotes that the rest of the line is a comment. FilterPath "disk path" Specifies the disk path where the filter programs can be found. TempPath "disk path" Specifies the disk path where any temporary file(s) will be created. InPath "disk path" OutPath "disk path" These set the initial directories for the input and output file requesters. (Of course, you can read and write from/to any directory; these are just for convenience.) UsePipes 0/1 FastAnalyze 0/1 Interlace 0/1 HSqueeze 0/1 These (optional) lines specify the initial values for HamLab's options. Cache12Bit size (32 bit signed value) This specifies the maximum size, in bytes, of HamLab's 12-bit temporary data that will be kept in RAM. If an image requires more room than this value, it will be kept in a temporary file. Some useful values to use here are: 0 -- always use a file -1 -- always keep it in memory 130000 -- keep 320 x 200 and smaller in RAM Filter "matchstring" "filtername" One of these lines must be present for every input filter. The first string is the pattern which identifies that type of file. The second is the name of the filter program. SUGGESTED CONFIGURATIONS: If you've got memory to burn, leave UsePipes turned off, set TempPath to RAM: and set Cache12Bit to -1. This will keep both 24-bit and 12-bit temporary images in memory. Beware, though, a 640 x 480 image will take up about 1.5 MEGS just in temporary files. HamLab and its input filters are "pure" code, so they can be made resident if you so desire. If you're short on memory, turn UsePipes on, set TempPath to a disk directory (a hard disk is nice, but not necessary) and set Cache12Bit to something low, like 0. This will eliminate the 24 bit file and keep the 12-bit temporary file on disk. If you then save a picture without displaying it first, then HamLab will only need a few lines of the picture in memory at a time. Displaying the picture is the only thing that requires any significant amounts of CHIP RAM. Note that a 640 x 480 HAM image takes about 230K of CHIP ram, though not all contiguous.