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