TopWare 18: Liquid

home *** CD-ROM | disk | FTP | other *** search

/ TopWare 18: Liquid / Image.iso / liquid / top1057 / dyeworks.doc next >

Wrap

Text File | 1994-03-24 | 17KB | 427 lines

DYEWORKS Version 1.31 - Color Reduction/Promotion/Manipulation ============================================================= The author's address: Stefan Reich Bjoernsonweg 12e 22587 Hamburg Germany Tel/Fax: 0049 40 86 31 62 (if you happen to speak German) CIS: [100117,1415] "Dyeworks 1.31" software is freely distributable as long as this document accompanies the executable DYEWORKS.EXE and both files remain unchanged. However, the program may not be included in a commercial product without written permission from the author. The GIF encoder/decoder implemented in Dyeworks 1.31 is based on C routines from "Fractint" which are copyrighted (c) 1987 by Steven A. Bennett. What is it? ----------- Dyeworks - reads and writes GIF, PCX, Targa, BMP and POV-Ray (DKBTrace) dump format - converts between color depths: grayscale, 256 colors, HiColor, TrueColor 24, TrueColor 32 - reduces true color bitmaps to VGA-suited 256 colors or to any given number of colors - shrinks pictures with anti-aliasing; adjusts contrast, brightness and gamma - is F A S T! - offers a variety of dithering processes for optimal results - requires (almost) constant amounts of memory and time, regardless of image size and contents (well, ok, time is size-depending) How you use it -------------- Dyeworks is batch-driven. That is, all parameters needed are supplied on the DOS command line. This makes it possible to process many files in a row without further user interaction. The usage is: DYEWORKS <option> <option> <option> ... Options are: *General Options -h,-? or no option Displays a help screen showing available options. -i<file> Specifies the input file. Currently supported are CompuServe's Graphics Interchange Format (GIF), PC Paintbrush (PCX), Targa, Windows Bitmap (BMP) and POV-Ray dump format. Syntax 1: -o<file> Syntax 2: -o(type)<file> Specifies the output file. Its file type may be different from the input file's type; if necessary, conversion is done. If no output file is given, Dyeworks just reads and displays. *Input and output file may not be identical!* File types: (g) Grayscale (8 Bits) (8) 256 color palette (out of 256K colors) (16) HiColor (3*5 Bits) (24) TrueColor (3*8 Bits) (32) TrueColor+Alpha (3*8+8 Bits) Note: "Alpha" is an 8 bit wide field to store additional information for each pixel (e.g. a transparency value). Dyeworks ignores it when reading. When writing, all alpha values are set to zero. These are all the possible combinations of file types and formats (R=readable, W=writable, Default=default output file type when none is specified): (g) (8) (16) (24) (32) Default TGA Uncompressed RW RW RW RW RW (24) TGA Compressed R R R R GIF87a RW (8) GIF89a R PCX RW RW (8) BMP Uncompressed R R R R R DIS (POV-Ray) RW (24) Another note: The GIF encoder attaches greater weight to speed than to compression efficiency. In other words, there are programs that make GIFs around 1% smaller than Dyeworks does; however, there is no program that produces GIFs as fast as Dyeworks does (as far as I know). *Wildcards* Both input and output file name may contain wildcards. The input file name follows the usual DOS wildcard conventions (allowing '?' and '*'). Dyeworks will process all files that match the input file name. If an output file name with wildcards is given, it will be used as a mask to convert the name of the current input file. Here, extended wildcards are allowed: Modifier Function ---------------------------------------- ? copy one character \ * copy all remaining characters | as understood by DOS a replace one character with 'a' / # delete one character \ unique to ^a insert character 'a' / Dyeworks See examples. +o Tells Dyeworks to <o>verwrite the output file(s) in case it/they already exist(s). Without this option, Dyeworks will not change an existing file. +d (the default) Displays picture while converting, in case the following conditions are met: - a VGA adapter is detected, - the picture is less or equal to 320 (width) * 200 (height) pixels in size (no SVGA support so far, sorry), and - there is no output file or it is of format '256 colors'. As soon as the picture is complete, Dyeworks waits for a key to be pressed. So if you want to convert multiple files continuously, make sure to specify "-d"! -d Disables graphical display. +q (quiet mode) Disables text display. This option does NOT imply "-d". *Histograms* Syntax 1: -hn<file> (New histogram file) Syntax 2: -ha<file> (Add histogram to file) These options scan the image and build up a histogram that stores detailed information about the colors used in the image; then, the histogram is saved into a file. "-hn<file>" starts with an empty histogram; "-ha<file>" reads the histogram from the file (that must exist), adds the new colors to it, and saves it again. You need such an on-disk-histogram when a palette is supposed to fit multiple images. In this case, you would first scan all the images with "-ha<file>", then convert the pictures down to 256 colors using "-hr<file>". *True color manipulations Any image data read by Dyeworks (regardless of the format) is first converted into true color. Now the manipulations listed below may be executed. The last step is either saving the true color data, or creating a palette for 256 color output. -s<factor> (factor=1-100) Shrinks the picture isometrically: new width = old width / factor new height = old height / factor The shrinking process doesn't just remove pixels from the picture: any program could give you that! No, it performs anti- aliasing by averaging each square that will be deflated to one pixel of the final image. One application of this feature is to receive a kind of anti- aliasing different from the one POV-Ray does, in terms of smoothing without introducing noise. To obtain this effect, render a picture at, let's say, 1280x800, and shrink it down to 320x200. I know, it's an immense size, and you will especially get problems with your hard disk space (if you don't use SuperStor(TM) :-). For the start, you could try a resolution of 640x400. Rendering this will take a time comparable to that a 320x200 raytracing with "anti-alias"-option on would need. This option is also very useful for postprocessing the output of (handy) scanners. Here, shrinking a) anti-aliases, and b) reduces irregularities of scanner and scanned image (e.g., the moiré effect occuring when scanning an image that was printed with a halftone pattern). +m Mirrors picture = swaps left and right. +vd +vc These options concern the reduction from the 16 Million color range (e.g.) POV-Ray produces to the 256 thousand color range a (standard) VGA adapter supports. This operation is supposed to precede a VGA palette creation, but in the first step leaves a true color image that could be saved as well (but who would want to do so?). Anyway, here is how it works: The option "+vc" simply cuts off the two least significant bits. (A little bit of computer math: 16 Million = 3*8 Bits; 262,144 = 3*6 Bits.) To cut a long story short: "+vc" is bad for gradients, but good for large areas of constant color, because it prevents "-pd" dithering (if turned on) from trying to dither a color a VGA card just isn't able to display. "+vd" cuts off two bits also, but remembers the "error" it makes by doing so, in order to correct this error with the next pixels processed. (You have guessed it: This is known as "dithering" :-) Using "+vd" together with "-pd" (s.b., together they're "DoubleDither") gives you the smoothest gradients you've ever seen. Try it: Render POV-Ray's "LAMP.POV" (this will take some hours), and display the output using Dyeworks (this will take some seconds). Note: With HiColor output, there will be a reduction from 16 Million to 32,768 (rather than 262,144) colors. Apart from this difference, the above said applies. -v (default) No color range reduction takes place. This can mean several things: - The true color picture remains unchanged. - If "-pd" option is turned on, it will do all the dithering work - AFTER the palette is chosen. One reason for the superiority of DoubleDither is the fact that palette creation takes place when most (or all) of the dithering work is already done. This makes it possible to design a palette more closely aligned to the picture's real needs. - If "-pn" is turned on, the effect will be a cut-off similar to the one "+vc" would do. The same thing happens in case of a HiColor output. *256 color output (and/or display) Syntax 1: -c<colors> Syntax 2: -c<firstentry>,<colors> (default: -c1,256) Sets the maximum number of output colors. For example, if you say "-c100", at least 156 palette entries will be left blank. By the way, the palette will always be sorted by descending frequency. (In other words: most popular colors first, least popular colors last.) Thus, if a (Windows) graphics software cuts off the last 16 or 20 entries it needs for itself, it won't do much harm. <firstentry> specifies the first palette entry to use (1-256). -pd -pl -pn (default: -pd) These options influence the way the original picture's colors are assigned to the new palette. -pn seeks the "nearest" available color (in the RGB cube). -pd does so, too, but superposes a full dither that does not "forget" any error it has made (see "-pd" section above). -pl dithers also, but in a much more "sloppy" way. Only great errors will affect other pixels. -e<max> (1-256, default: -e12) Limits the error that is saved and transported. This prevents "-pd" dithering from making bad things worse: e.g., if a much too bright color had to be chosen, the next pixel would be much too dark instead in order to correct the error made. (Usually, this doesn't occur unless you limit the number of colors (s.a.).) "-e12" means that any error beyond a distance of 12 true color shades (=3 VGA shades, or three 64ths of the distance between black and white) will be ignored. -hr<file> Reads the histogram from a file, rather than building a histogram from the image read. See "Histograms" section above. Examples -------- C:>dyeworks -inicepic Standard command to display true color pictures ("nicepic.tga" in this case). Palette creation; single dither; no output file. C:>dyeworks -ilamp -olamp Reads "lamp.tga", creates a palette, dithers, displays if possible, and saves to "lamp.gif". C:>dyeworks -ibigpic.dis -s5 -o(16)smallpic.tga Reads "bigpic.dis", shrinks it to a fifth (or a twentyfifth of its surface), converts down to HiColor (without dithering), and writes to "smallpic.tga". Displaying is not possible since no palette is generated. C:>for %p in (pic1 pic2 pic3) do dyeworks -i%p.dis -o%p.pcx +vd -d -q This call uses DOS "for" command to process three images in a row. "pic1.dis", "pic2.dis" and "pic3.dis" will be converted to "pic1.pcx", "pic2.pcx" and "pic3.pcx", respectively. DoubleDither is turned on. Text and graphic display are disabled. In a batch file, the line would look slightly different: for %%p in (pic1 pic2 pic3) do dyeworks -i%%p.dis -o%%p.pcx +vd -d -q C:>dyeworks -ianim*.dis -o^_*.gif +vd -d -q Converts all POV-Ray dump files beginning "anim" in the current directory to files with "_" inserted at the front and GIF extension. For example, "anim001.dis" would be converted to "_anim001.gif". C:>dyeworks -imanycols.gif -c128 -olesscols.gif Reads "manycols.gif", creates a new palette with up to 128 colors, and writes to "lesscols.gif". Note that if reading a 256 color file with no shrinking applied, "+vd" and "+vc" options are ignored since color range already is 262,144. Error Levels ------------ Dyeworks returns an error level depending on successful completion or occurrence of errors. The error level can be checked using DOS "if errorlevel" command. See MS-DOS user's guide for details. These are the codes: 0 No Error 1 Help screen displayed 2 Could not understand command line 3 Out of memory 4 Input file is corrupt or does not exist 5 Could not write output file (bad directory, disk full?) 6 (At least one) output file exists, skipped 7 Histogram overflow Warranty -------- I, the author, hereby guarantee that Dyeworks is the cheapest, fastest and best VGA color reduction utility available. However, if you find a program that produces better results in shorter time, you will get your money back. Contact me, and I will send you a cheque for 0.00 US-$ (or, if you like, 0.00 UK pounds, 0 Yen or any other currency :-). Joking apart, contact me, and I will see what I can do for Dyeworks 2.0. If you want to include Dyeworks in a commercial software or package: contact me also. Design Limits ------------- Minimum operating system: MS-DOS 3.0 Minimum processor: 80286 (Pentium is OK, too) Minimum free DOS memory: 400,000-540,000 Bytes (the latter may apply for GIF encoding) Minimum graphics adapter for display: VGA Maximum bitmap size before shrinking: 20480*infinite Maximum bitmap size after shrinking: 1280*infinite (1280*1024 is guaranteed to fit into histogram) Revision History (major versions only) ---------------- 1.31 Bugfix, accelerations 1.3 Multi-file (wildcard) support; histogram sharing New effects (contrast, brightness, gamma) New formats (Targa Compressed, BMP; HiColor, Grayscale) EMS support for caching purposes ...and various speed improvements 1.2 Final GIF encoder/decoder: fast & stable 1.0 First version; distributed in CompuServe's Graphics Developers+ Forum Final note: There is a Protected Mode (DPMI) version of Dyeworks available that consumes 400-600K of extended memory and very little DOS memory (very useful when calling Dyeworks as a child process). Contact me if you want to have it. I was not sure whether anyone could need a DPMI Dyeworks, and considered the package including both versions a bit too large to upload it in CompuServe. Have fun!