home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 19 / CD_ASCQ_19_010295.iso / dos / graphic / dyeworks / dyeworks.doc next >
Text File  |  1994-10-26  |  19KB  |  479 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.        DYEWORKS Version 1.34 - Color Reduction/Promotion/Manipulation
  10.        =============================================================
  11.  
  12.        The author's address:
  13.  
  14.               Stefan Reich
  15.               Bjoernsonweg 12e
  16.               22587 Hamburg
  17.               Germany
  18.               Tel/Fax: 0049 40 86 31 62 (if you happen to speak German)
  19.               CompuServe CIS: [100117,1415]
  20.  
  21.        "Dyeworks 1.34" software is freely distributable as long as this
  22.        document accompanies the executable DYEWORKS.EXE and both files
  23.        remain unchanged. However, the program may not be included in a
  24.        commercial product without written permission from the author.
  25.        The GIF encoder/decoder implemented in Dyeworks 1.34 is based on
  26.        C routines from "Fractint" which are copyrighted (c) 1987 by
  27.        Steven A. Bennett.
  28.  
  29.  
  30.        What is it?
  31.        -----------
  32.  
  33.        Dyeworks
  34.        - reads and writes GIF, PCX, Targa, BMP and POV-Ray (DKBTrace)
  35.           dump format
  36.        - converts between color depths: grayscale, 256 colors, HiColor,
  37.           TrueColor 24, TrueColor 32
  38.        - reduces true color bitmaps to VGA-suited 256 colors or to any
  39.           given number of colors
  40.        - shrinks pictures with anti-aliasing; adjusts contrast,
  41.           brightness and gamma
  42.        - is F A S T!
  43.        - offers a variety of dithering processes for optimal results
  44.           (Try +vd!)
  45.        - requires (almost) constant amounts of memory and time,
  46.           regardless of image size and contents
  47.          (well, ok, time is size-depending)
  48.  
  49.  
  50.        How you use it
  51.        --------------
  52.  
  53.        Dyeworks is batch-driven. That is, all parameters needed are
  54.        supplied on the DOS command line. This makes it possible to
  55.        process many files in a row without further user interaction.
  56.  
  57.        The usage is:
  58.  
  59.                DYEWORKS <option> <option> <option> ...
  60.  
  61.        (The order is meaningless.)
  62.  
  63.        Options are:
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.        *General Options
  71.  
  72.        -h,-? or no option
  73.        Displays a help screen showing available options.
  74.  
  75.        -i<file>
  76.        Specifies the input file. Currently supported are CompuServe's
  77.        Graphics Interchange Format (GIF), PC Paintbrush (PCX), Targa
  78.        (TGA), Windows Bitmap (BMP) and POV-Ray dump format.
  79.  
  80.        Syntax 1: -o<file>
  81.        Syntax 2: -o(type)<file>
  82.        Specifies the output file. Its file type may be different from
  83.        the input file's type; if necessary, conversion is done.
  84.        If no output file is given, Dyeworks just reads and displays.
  85.        *Input and output file may not be identical!*
  86.  
  87.        File types:
  88.  
  89.        (g)  Grayscale         (8 Bits)
  90.        (8)  256 color palette (out of 256K colors)
  91.        (16) HiColor           (3*5 Bits)
  92.        (24) TrueColor         (3*8 Bits)
  93.        (32) TrueColor+Alpha   (3*8+8 Bits)
  94.  
  95.        Note: "Alpha" is an 8 bit wide field to store additional
  96.        information for each pixel (e.g. a transparency value). Dyeworks
  97.        ignores it when reading. When writing, all alpha values are set
  98.        to zero.
  99.  
  100.        These are all the possible combinations of file types and
  101.        formats (R=readable, W=writable, Default=default output file
  102.        type when none is specified):
  103.  
  104.                            (g)    (8)   (16)   (24)   (32)   Default
  105.        TGA Uncompressed    RW     RW     RW     RW     RW     (24)
  106.        TGA Compressed      R      R      R      R      R
  107.        GIF87a                     RW                           (8)
  108.        GIF89a                     R
  109.        PCX                        RW            RW             (8)
  110.        BMP Uncompressed    R      R      R      R      R
  111.        DIS (POV-Ray)                            RW            (24)
  112.  
  113.        Another note: The GIF encoder attaches greater weight to speed
  114.        than to compression efficiency. In other words, there are
  115.        programs that make GIFs around 1% smaller than Dyeworks does;
  116.        however, there is no program that produces GIFs as fast as
  117.        Dyeworks does (as far as I know). By the way, I've already seen
  118.        GIF encoders (of some very expensive utilities...) compressing
  119.        even less efficient than Dyeworks.
  120.  
  121.        *Wildcards*
  122.  
  123.        Both input and output file name may contain wildcards. The input
  124.        file name follows the usual DOS wildcard conventions (allowing
  125.        '?' and '*'). Dyeworks will process all files that match the
  126.        input file name. If an output file name with wildcards is given,
  127.        it will be used as a mask to convert the name of the current
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.        input file. Here, extended wildcards are allowed:
  135.  
  136.        Modifier   Function
  137.        ----------------------------------------
  138.            ?      copy one character             \
  139.            *      copy all remaining characters  | as understood by DOS
  140.            a      replace one character with 'a' /
  141.            #      delete one character           \ unique to
  142.            ^a     insert character 'a'           / Dyeworks
  143.  
  144.        See examples at the end of this document.
  145.  
  146.        +o
  147.        Tells Dyeworks to <o>verwrite the output file(s) in case it/they
  148.        already exist(s). Without this option, Dyeworks will not change
  149.        an existing file.
  150.  
  151.        +d (the default)
  152.        Displays picture while converting, in case the following
  153.        conditions are met:
  154.        - a VGA adapter is detected,
  155.        - the picture is less or equal to 320 (width) * 200 (height)
  156.          pixels in size (no SVGA support so far, sorry), and
  157.        - there is no output file or it is of format '256 colors'.
  158.        As soon as the picture is complete, Dyeworks waits for a key to
  159.        be pressed. So if you want to convert multiple files
  160.        continuously (or call Dyeworks from another program), make sure
  161.        to specify "-d"!
  162.  
  163.        -d
  164.        Disables graphical display.
  165.  
  166.        +q (quiet mode)
  167.        Disables text display. This option does NOT imply "-d".
  168.  
  169.        *Histograms*
  170.  
  171.        Syntax 1: -hn<file>   (New histogram file)
  172.        Syntax 2: -ha<file>   (Add histogram to file)
  173.  
  174.        These options scan the image and build up a histogram that
  175.        stores detailed information about the (true-)colors used in the
  176.        image; then, the histogram is saved into a file. "-hn<file>"
  177.        starts with an empty histogram; "-ha<file>" reads the histogram
  178.        from the file (that must exist), adds the new colors to it, and
  179.        saves it again.
  180.        You need such an on-disk-histogram when a palette is supposed to
  181.        fit multiple images. In this case, you would first scan all the
  182.        images with "-ha<file>", then convert the pictures down to 256
  183.        colors using "-hr<file>".
  184.  
  185.  
  186.        *True color manipulations
  187.  
  188.        Any image data read by Dyeworks (regardless of the format) is
  189.        first converted into true color. Now the manipulations listed
  190.        below may be executed. The last step is either saving the true
  191.        color data, or creating a palette for 256 color output.
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.        -s<factor> (factor=1-100)
  199.        Shrinks the picture isometrically:
  200.  
  201.            new width  = old width / factor
  202.            new height = old height / factor
  203.  
  204.        The shrinking process doesn't just remove pixels from the
  205.        picture: any program could give you that! No, it performs anti-
  206.        aliasing by averaging the pixels of each square that will be
  207.        deflated to one pixel of the final image.
  208.        One application of this feature is to receive a kind of anti-
  209.        aliasing different from the one POV-Ray does, in terms of
  210.        smoothing without introducing noise. To obtain this effect,
  211.        render a picture at, let's say, 1280x800, and shrink it down to
  212.        320x200. I know, it's an immense size, and you will especially
  213.        get problems with your hard disk space (if you don't use
  214.        SuperStor(TM) :-). For the start, you could try a resolution of
  215.        640x400. Rendering this will take a time comparable to that a
  216.        320x200 raytracing with "anti-alias"-option on would need.
  217.        This option is also very useful for postprocessing the output of
  218.        (handy) scanners. Here, shrinking
  219.        a) anti-aliases, and
  220.        b) reduces irregularities of scanner and/or scanned image
  221.           (e.g., the moiré effect occuring when scanning an image that
  222.           was printed with a halftone pattern).
  223.  
  224.        +m
  225.        Mirrors picture = swaps left and right.
  226.  
  227.        +f
  228.        Flips picture = turns it upside down. This is possible with few
  229.        formats only (see help screen).
  230.  
  231.        +cc<percentage> (-100..+100)
  232.        Adjusts contrast. "+cc-100" gives a totally black image,
  233.        "+cc+100" kills all nuances, reducing anything to no more than 8
  234.        colors. "+cc0" has no effect.
  235.  
  236.        +cb<percentage> (-100..+100)
  237.        Adjust brightness.
  238.  
  239.        +cg[r][g][b]<gamma> (0.01-10.0)
  240.        Adjusts the gamma value of one or more color channels (r=red,
  241.        g=green, b=blue). Gamma correction is a somewhat complicated
  242.        subject; what you need to know, basically is that higher gamma
  243.        values result in brighter images. Default is gamma=1.0.
  244.        If you don't specify a channel, all three are affected (e.g.
  245.        "+cg1.4", rather than "+cgrb1.4" (red&blue only)).
  246.  
  247.        +vd +vc
  248.        These options concern the reduction from the 16 Million color
  249.        range (e.g.) POV-Ray produces to the 256 thousand color range a
  250.        (standard) VGA adapter supports. This operation is supposed to
  251.        precede a VGA palette creation, but in the first step leaves a
  252.        true color image that could be saved as well (but who would want
  253.        to do so?). Anyway, here is how it works:
  254.        The option "+vc" simply cuts off the two least significant bits.
  255.        (A little bit of computer math: 16 Million = 3*8 Bits; 262,144 =
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.        3*6 Bits.) To cut a long story short: "+vc" is bad for
  263.        gradients, but good for large areas of constant color, because
  264.        it prevents "-pd" dithering (if turned on) from trying to dither
  265.        a color a VGA card just isn't able to display.
  266.        "+vd" cuts off two bits also, but remembers the "error" it makes
  267.        by doing so, in order to correct this error with the next pixels
  268.        processed. (You have guessed it: This is known as "dithering"
  269.        :-)
  270.        Using "+vd" together with "-pd" (s.b., together they're
  271.        "DoubleDither") gives you the smoothest gradients you've ever
  272.        seen. Try it: Render POV-Ray's "LAMP.POV" (this will take some
  273.        hours), and display the output using Dyeworks (this will take
  274.        some seconds).
  275.  
  276.        Note: With HiColor output, there will be a reduction from 16
  277.        Million to 32,768 (rather than 262,144) colors. Apart from this
  278.        difference, the above said applies.
  279.  
  280.        -v (default)
  281.        No color range reduction takes place.
  282.        This can mean several things:
  283.        - The true color picture remains unchanged.
  284.        - If "-pd" option is turned on, it will do all the dithering
  285.        work - AFTER the palette is chosen. One reason for the
  286.        superiority of DoubleDither is the fact that palette creation
  287.        takes place when most (or all) of the dithering work is already
  288.        done. This makes it possible to design a palette more closely
  289.        aligned to the picture's real needs.
  290.        - If "-pn" is turned on, the effect will be a cut-off similar to
  291.        the one "+vc" would do. The same thing happens in case of a
  292.        HiColor output.
  293.  
  294.  
  295.        *256 color output (and/or display)
  296.  
  297.        Syntax 1: -c<colors>
  298.        Syntax 2: -c<firstentry>,<colors>  (default: -c1,256)
  299.        Sets the maximum number of output colors. For example, if you
  300.        say "-c100", at least 156 palette entries will be left blank.
  301.        By the way, the palette will always be sorted by descending
  302.        frequency. (In other words: most popular colors first, least
  303.        popular colors last.) Thus, if a (Windows) graphics software
  304.        cuts off the last 16 or 20 entries it needs for itself, it won't
  305.        do much harm.
  306.        <firstentry> specifies the first palette entry to use (1-256).
  307.  
  308.        -pd -pl -pn (default: -pd)
  309.        These options influence the way the original picture's colors
  310.        are assigned to the new palette.
  311.        -pn seeks the "nearest" available color (in the RGB cube).
  312.        -pd does so, too, but superposes a full dither that does not
  313.        "forget" any error it has made (see "+vd" section above).
  314.        -pl dithers also, but in a much more "sloppy" way. Only great
  315.        errors will affect other pixels.
  316.  
  317.        -e<max> (1-256, default: -e12)
  318.        Limits the error that is saved and transported. This prevents
  319.        "-pd" dithering from making bad things worse: e.g., if a much
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.        too bright color had to be chosen, the next pixel would be much
  327.        too dark instead in order to correct the error made. (Usually,
  328.        this doesn't occur unless you limit the number of colors
  329.        (s.a.).) "-e12" means that any error beyond a distance of 12
  330.        true color shades (=3 VGA shades, or twelve 256ths of the
  331.        distance between black and white) will be ignored.
  332.  
  333.        -hr<file>
  334.        Reads the histogram from a file, rather than building a
  335.        histogram from the image read. See "Histograms" section above.
  336.  
  337.  
  338.        Examples
  339.        --------
  340.  
  341.        C:>dyeworks -inicepic
  342.        Standard command to display true color pictures ("nicepic.tga"
  343.        in this case). Palette creation; single dither; no output file.
  344.  
  345.        C:>dyeworks -ilamp -olamp
  346.        Reads "lamp.tga", creates a palette, dithers, displays if
  347.        possible, and saves to "lamp.gif".
  348.  
  349.        C:>dyeworks -ibigpic.dis -s5 -o(16)smallpic.tga
  350.        Reads "bigpic.dis", shrinks it to a fifth (or a twentyfifth of
  351.        its surface), converts down to HiColor (without dithering), and
  352.        writes to "smallpic.tga". Displaying is not possible since no
  353.        palette is generated.
  354.  
  355.        C:>for %p in (pic1 pic2 pic3) do dyeworks -i%p.dis -o%p.pcx +vd
  356.        -d -q
  357.        This call uses DOS "for" command to process three images in a
  358.        row. "pic1.dis", "pic2.dis" and "pic3.dis" will be converted to
  359.        "pic1.pcx", "pic2.pcx" and "pic3.pcx", respectively.
  360.        DoubleDither is turned on. Text and graphic display are
  361.        disabled.
  362.        In a batch file, the line would look slightly different:
  363.        for %%p in (pic1 pic2 pic3) do dyeworks -i%%p.dis -o%%p.pcx +vd
  364.        -d -q
  365.  
  366.        C:>dyeworks -ianim*.dis -o^_*.gif +vd -d -q
  367.        Converts all POV-Ray dump files beginning "anim" in the current
  368.        directory to files with "_" inserted at the front and GIF
  369.        extension. For example, "anim001.dis" would be converted to
  370.        "_anim001.gif".
  371.  
  372.        C:>dyeworks -imanycols.gif -c128 -olesscols.gif
  373.        Reads "manycols.gif", creates a new palette with up to 128
  374.        colors, and writes to "lesscols.gif". Note that if reading a 256
  375.        color file with no shrinking applied, "+vd" and "+vc" options
  376.        are ignored since color range already is 262,144.
  377.  
  378.        Step 1:
  379.        C:>dyeworks +vd -imorf* -hnmymorf
  380.        C:>dyeworks +vd -ipic1 -hamymorf
  381.        C:>dyeworks +vd -ipic2 -hamymorf
  382.        Fills histogram file "mymorf.dyh" with color information for the
  383.        files "morf*.tga", "pic1.tga" and "pic2.tga". Uses DoubleDither.
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.        Step 2:
  391.        C:>dyeworks +vd -imorf* -o*.gif -hrmymorf
  392.        C:>dyeworks +vd -ipic1 -o*.gif -hrmymorf
  393.        C:>dyeworks +vd -ipic2 -o*.gif -hrmymorf
  394.        Converts "morf*.tga", "pic1.tga" and "pic2.tga" to "morf*.gif",
  395.        "pic1.gif" and "pic2.gif", respectively, using DoubleDither. All
  396.        the GIFs produced will have the same palette.
  397.  
  398.        Error Levels
  399.        ------------
  400.  
  401.        Dyeworks returns an error level depending on successful
  402.        completion or occurrence of errors. The error level can be
  403.        checked using DOS "if errorlevel" command. See MS-DOS user's
  404.        guide for details.
  405.        These are the codes:
  406.  
  407.         0  No Error
  408.         1  Help screen displayed
  409.         2  Could not understand command line
  410.         3  Out of memory
  411.         4  Input file is corrupt or does not exist
  412.         5  Could not write output file (bad directory, disk full?)
  413.         6  (At least one) output file exists, skipped
  414.         7  Histogram overflow
  415.  
  416.  
  417.        Warranty
  418.        --------
  419.  
  420.        I, the author, hereby guarantee that Dyeworks is the cheapest,
  421.        fastest and best VGA color reduction utility available. However,
  422.        if you find a program that produces better results in shorter
  423.        time, you will get your money back. Contact me, and I will send
  424.        you a cheque for 0.00 US-$ (or, if you like, 0.00 UK pounds, 0
  425.        Yen or any other currency :-). Joking apart, contact me, and I
  426.        will see what I can do for a Dyeworks 2.0 (you like). If you
  427.        want to include Dyeworks in a commercial software or package:
  428.        contact me also.
  429.  
  430.  
  431.        Design Limits
  432.        -------------
  433.  
  434.        Minimum operating system:             MS-DOS 3.0
  435.        Minimum processor:                    80286 (Pentium is OK, too)
  436.        Minimum free DOS memory:              400,000-540,000 Bytes
  437.                                  (the latter may apply for GIF encoding)
  438.        Minimum graphics adapter for display: VGA
  439.        Maximum bitmap size before shrinking: 20480*infinite
  440.        Maximum bitmap size after shrinking:  1280*infinite
  441.                          (1280*1024 is guaranteed to fit into histogram)
  442.  
  443.  
  444.        Revision History (major versions only)
  445.        ----------------
  446.  
  447.        1.34 Bugfix (compressed 16-bit Targa load)
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.        1.32 Published on the POV-Ray CD (contact Chris Cason
  456.             [CIS: 100032,1644])
  457.             German version (GO MUTFORUM)
  458.  
  459.        1.3  Multi-file (wildcard) support; histogram sharing
  460.             New effects (contrast, brightness, gamma)
  461.             New formats (Targa Compressed, BMP; HiColor, Grayscale)
  462.             EMS support for caching purposes
  463.             ...and various speed improvements
  464.  
  465.        1.2  Final GIF encoder/decoder: fast & stable
  466.  
  467.        1.0  First version; distributed in CompuServe's Graphics
  468.             Developers+ Forum
  469.  
  470.        Final note: There is
  471.        a) a German version (GO MUTFORUM) and
  472.        b) a Protected Mode (DPMI) version of Dyeworks available that
  473.        consumes 400-600K of extended memory and very little DOS memory
  474.        (very useful when calling Dyeworks as a child process). Contact
  475.        me if you want to have it. I was not sure whether anyone could
  476.        need a DPMI Dyeworks, and considered the package including both
  477.        versions a bit too large to upload it in CompuServe.
  478.  
  479.        Have fun!