











                                    Image Alchemy





                                     Version 1.7
































                               Handmade Software, Inc.









 

       Notice                Handmade Software, Inc. makes no warranty of any
                             kind either expressed or implied.  In particular
                             we make no warranty as to merchantability or
                             fitness for a particular purpose.


                             In no event shall Handmade Software, Inc. be
                             liable for any errors contained herein or for
                             incidental or consequential damages in connection
                             with the furnishing, performance, or use of the
                             Image Alchemy product or documentation.


                             This document contains proprietary information
                             which is protected by copyright.  No part of this
                             document may be photocopied, reproduced, or
                             translated without the prior written consent of
                             Handmade Software, Inc.


                             The information in this document is subject to
                             change without notice.

























       Copyright             Copyright (c) 1990-1994 Handmade Software, Inc.,
                             Fremont, California

                             All Rights Reserved





                   Copyright (c) 1990-1994 Handmade Software, Inc.           ii 







                            Image Alchemy was written by:


                                 Marcos H. Woehrmann
                                 Allan N. Hessenflow
                                    David Kettmann
                                  Paul H. Yoshimune


























                               Handmade Software, Inc.
                              48820 Kato Road, Suite 110
                                  Fremont, CA  94538

                                    1 800 358 3588
                                   +1 510 252 0101
                                 +1 510 252 0909 fax
                                 +1 510 252 0929 BBS

                              Internet:  hsi@netcom.COM
                               CompuServe:  71330, 3136






                   Copyright (c) 1990-1994 Handmade Software, Inc.          iii 

       Trademarks            Image Alchemy is a trademark of Handmade Software,
                             Inc.


                             All other products or services mentioned in this
                             manual, including:  IBM PC, IBM PC AT, 80286,
                             80386, 80486, VGA, 8514/A, Paradise, Everex,
                             Trident, Video 7, Tseng Labs, Western Digital, MS-
                             DOS, PC-DOS, SPARC, Sun, SPARCstation,
                             SPARCserver, SunOS, Targa, PostScript, EPS,
                             Encapsulated PostScript, GIF, ILBM, IFF,
                             Macintosh, Silicon Graphics, SGI, PCX, TIFF,
                             Windows, Windows BitMaP, EGA, PCL, HP, AI, PS/2,
                             HAM, PC Paintbrush, MacBinary, PHIPS, NeXT, C-
                             Cube, Storm Technology, Radius, ColorSqueeze,
                             VFCtool, Amiga, CompuServe, LaserJet, Times Roman,
                             and Gill Sans are trademarks, registered
                             trademarks, service marks, or registered service
                             marks of their respective companies or
                             organizations.

                             Even though they are never mentioned in this
                             document, you should know that Yellow Pages is a
                             registered trademark in the United Kingdom of
                             British Telecommunications plc., and may also be a
                             trademark of various telephone companies around
                             the world.





























       iv          Copyright (c) 1990-1994 Handmade Software, Inc. 





       Contents
       ------------------------------------------------------------------------



       Chapter 0
          Introduction............................................1
          About This Manual.......................................2
          Document Conventions....................................3


       Chapter 1  Installation
          Introduction............................................5

          Image Alchemy for MS-DOS
            Required Equipment....................................6
            Optional Equipment....................................7
            Packing List..........................................7
            Installation Instructions.............................8
            Environment Variables.................................8

          UNIX Installation
            Required Equipment...................................17
            Packing List.........................................17
            Installation Instructions............................17
            Environment Variables................................18
            Differences between UNIX and MS-DOS..................19


       Chapter 2  Introduction
          Basic Instructions.....................................21
          Limitations on filenames...............................23
          Output Path............................................23
          Using Response Files...................................24
          Multiple Runs of Alchemy...............................26


       Chapter 3  Graphical User Interface (MS-DOS only)
          Introduction...........................................29
          Starting the GUI.......................................29
          The Main Screen........................................30
          Quitting the GUI.......................................31
          The File Sub-Menu......................................31
          The Resize Sub-Menu....................................34
          The Palette Sub-Menu...................................34
          The Colors Sub-Menu....................................34
          The Dither Sub-Menu....................................35


       Chapter 4  Output Options
          Introduction...........................................37

                   Copyright (c) 1990-1994 Handmade Software, Inc.            v 

          Identifying Image Files................................39
          MacBinary..............................................39
          Other Information......................................39

          Image File Formats
            ADEX.................................................41
            Adobe Acrobat PDF....................................42
            Alpha Microsystems BMP...............................44
            Autologic............................................45
            AVHRR................................................46
            Binary Information File (BIF)........................48
            Calcomp CCRF.........................................50
            CALS.................................................52
            Core IDC.............................................53
            Cubicomp PictureMaker................................55
            Dr. Halo CUT.........................................57
            Encapsulated PostScript..............................58
            ER Mapper Raster.....................................61
            Erdas LAN/GIS........................................63
            First Publisher ART..................................66
            Freedom of Press.....................................67
            GEM VDI Image File...................................69
            GIF..................................................71
            GOES.................................................73
            Hitachi Raster Format................................75
            HP Printer Command Language (PCL)....................76
            HP Raster Transfer Language (RTL)....................80
            HP-48sx Graphic Object (GROB)........................84
            HSI JPEG.............................................85
            HSI Palette..........................................86
            HSI Raw..............................................87
            IBM Picture Maker....................................88
            IFF/ILBM.............................................89
            Img Software Set.....................................90
            Jovian VI............................................91
            JPEG/JFIF............................................92
            Lumena CEL...........................................95
            Macintosh PICT/PICT2.................................96
            MacPaint.............................................98
            MTV Ray Tracer.......................................99
            Multi-Image Palette.................................100
            OS/2 Bitmap.........................................102
            PCPAINT/Pictor Page Format..........................103
            PCX.................................................105
            PDS.................................................108
            Portable BitMap (PBM)...............................110
            Puzzle..............................................112
            Q0..................................................113
            QDV.................................................114
            QRT Raw.............................................115
            RIX.................................................116
            Scodl...............................................117
            Silicon Graphics Image..............................120
            SPOT Image..........................................121
            Stork...............................................123

       vi          Copyright (c) 1990-1994 Handmade Software, Inc. 

            Sun Icon............................................125
            Sun Raster..........................................126
            Targa...............................................128
            TIFF................................................130
            Utah Raster Toolkit.................................132
            VITec...............................................134
            Vivid...............................................135
            Windows Bitmap......................................136
            WordPerfect Graphic File............................139
            XBM.................................................140
            XPM.................................................142
            XWD.................................................145


       Chapter 5  General Options
          Introduction..........................................147
          Conserve Memory.......................................148
          Display Image Stats...................................149
          Do Not Alter Output Filename..........................150
          Help..................................................151
          Override Input Type...................................152
          Overwrite.............................................154
          Program Information...................................155
          Quiet.................................................156
          Warnings..............................................157
          Wildcard..............................................158


       Chapter 6  Colour and Palette Options
          Introduction..........................................161
          Black and White.......................................162
          Colours...............................................163
          Dither................................................165
          EGA Palette...........................................167
          False Colour..........................................168
          Gamma Correction......................................169
          Match Palette.........................................171
          Negate................................................173
          Palette...............................................174
          Palette Selection.....................................176
          Spiff.................................................178
          True Colour (15 bits).................................180
          True Colour (16 bits).................................181
          True Colour (24 bits).................................182
          True Colour (32 bits).................................184
          Undercolour Removal...................................185
          Uniform Palette.......................................186


       Chapter 7  Scaling Options
          Introduction..........................................189
          Flip Image............................................190
          Mirror Image..........................................191
          Offset Image..........................................192
          Preserve Aspect Ratio.................................193

                   Copyright (c) 1990-1994 Handmade Software, Inc.          vii 

          Scale Image Horizontally..............................194
          Scale Image Vertically................................197
          Specify Image Aspect Ratio............................199
          Specify Image Resolution..............................201


       Chapter 8  Viewing Options (MS-DOS Only)
          Display Hardware......................................203
          Display Resolutions...................................206
          Offset View...........................................207
          View Image............................................208
          View Image in True Colour Mode........................209
          View Scaled Image.....................................211
          View Scaled Image in True Colour Mode.................213


       Chapter 9  Tutorial and Examples
          Introduction..........................................215


       Appendix A  Answers to Frequently Asked Questions
            ....................................................219


       Appendix B  Colour and Dithering
            ....................................................231


       Appendix C  JPEG Description
            ....................................................237


       Appendix D  Customer Support
            ....................................................241


       Appendix E  Binary Information Files (BIF)
            ....................................................243


       Appendix F  HSI Raw Files
            ....................................................247


       Appendix G  Undercolour Removal Files
            ....................................................253


       Appendix H  HSI PAL Files
            ....................................................257


       Appendix I  Acknowledgments
            ....................................................259


       viii        Copyright (c) 1990-1994 Handmade Software, Inc. 


       Appendix J  Other Useful Software
            ....................................................261


       Glossary
            ....................................................277


       References
            ....................................................281


       Index
            Not Included in the online documentation (sorry)









































                   Copyright (c) 1990-1994 Handmade Software, Inc.           ix 

























































       x           Copyright (c) 1990-1994 Handmade Software, Inc. 




                                                                              0



       Introduction to Image Alchemy
       ------------------------------------------------------------------------


       What is Image         Image Alchemy is a software utility that
       Alchemy?              manipulates computer image files.


                             Primarily, Image Alchemy converts between various
                             graphics file formats.  Image Alchemy can
                             translate between a large variety of file formats
                             including industry standards such as GIF and TIFF
                             as well as vendor-specific file formats such as
                             Sun Raster and Scodl.  Currently Alchemy supports
                             over 60 different formats, and new formats are
                             always being added; in fact, our goal is to have
                             Image Alchemy be able to read and write every
                             image file format in the world.


                             Image Alchemy can also resize an image, change the
                             number of colours in an image, change an image
                             from colour to black and white, and change the
                             colour space an image uses.


                             Finally, Image Alchemy performs JPEG compression.
                             This is a standard for image compression that can
                             achieve much higher compression ratios than
                             conventional compression techniques.  For further
                             information see Appendix C, "What is JPEG
                             Compression".

















                   Copyright (c) 1990-1994 Handmade Software, Inc.            1 

       About this manual     This manual is divided into 12 chapters, 11
                             appendices, a glossary, references, a colophon,
                             and an index.

               Chapter 0     Introduction and Conventions
               Chapter 1     Installation Instructions
               Chapter 2     Introduction to Alchemy
               Chapter 3     Graphical User Interface (MS-DOS only)
               Chapter 4     Output Options
               Chapter 5     General Options
               Chapter 6     Colour and Palette Options
               Chapter 7     Scaling Options
               Chapter 8     Viewing Options (MS-DOS only)
               Chapter 9     Tutorial and Examples
              Appendix A     Answers to Frequently Asked Questions
              Appendix B     Colour and Dithering
              Appendix C     JPEG Description
              Appendix D     Customer Support
              Appendix E     Binary Information Files (BIF)
              Appendix F     HSI Raw Files
              Appendix G     Undercolour Removal Files
              Appendix H     PAL Files
              Appendix I     Acknowledgments
              Appendix J     Other Useful Software
                Glossary
              References
                Colophon
                   Index




























       2           Copyright (c) 1990-1994 Handmade Software, Inc. 

       Document         Type style   Used for
       conventions

                        italic       Parameters.  You supply values for the
                                     items shown in italic.  For example, if
                                     the description of a command includes
                                     filename, you would type in the name of
                                     the desired file.

                        [ ]          Brackets.  Indicate optional items.


                        ...          Ellipses.  Indicates a list of items or
                                     items which may be repeated.


                        fixedspace   Examples of Alchemy usage which can be
                                     typed in exactly as written.  Many of the
                                     examples give file names which probably
                                     don't exist on your system; substitute
                                     different file names as appropriate.



































                   Copyright (c) 1990-1994 Handmade Software, Inc.            3 

























































       4           Copyright (c) 1990-1994 Handmade Software, Inc. 

                                                                              1



       Installing Image Alchemy
       ------------------------------------------------------------------------


       Overview              Installation of Image Alchemy is straightforward;
                             it involves copying the Alchemy program and
                             support files off of the supplied floppy disks or
                             tape onto your hard drive or network and setting
                             some environment variables.











































                   Copyright (c) 1990-1994 Handmade Software, Inc.            5 

       Image Alchemy for MS-DOS
       ------------------------------------------------------------------------


       Required              At a minimum you must have the following hardware
       equipment             and software to run Image Alchemy.

                Computer     An MS-DOS computer equipped with an 80286, 80386,
                             80486, Pentium, or better Intel processor.

                             Many of the conversions that Alchemy does are CPU
                             intensive, so a faster computer is definitely an
                             advantage.

                  Memory     At least 400k of free memory.


                             Some conversions and some images require more
                             memory (Alchemy will attempt to use all available
                             system memory, so if you get out-of-memory errors
                             or warnings try removing as many resident programs
                             as you can (also, installing MS-DOS 5.0, MS-DOS
                             6.0, or a 3rd party memory manager such as 386MAX
                             or QEMM will free up more memory)).


                             Alchemy makes use of extended and expanded memory
                             while performing conversions.  This can greatly
                             speed up the conversion process.  In general you
                             will need as much memory as the size of the image,
                             in pixels, being converted.  For example, a
                             640x480 true colour image will use 900k of memory.

              Hard drive     A hard drive with at least as much free space as
                             four times the size of the image being converted
                             (i.e. a 640x480 image will require up to
                             1.2 megabytes of free space).

        Operating system     MS-DOS or PC-DOS 3.x or greater (because of the
                             additional free memory available, use of MS-DOS
                             5.0 or higher is recommended).

       Optional              The following hardware is optional.
       equipment


                 Display     A supported SVGA, 8514/A, or XGA board, if you
                             wish to view images.


                             Supported SVGA boards include those with a VESA
                             driver or with the Paradise, Everex, Trident,
                             Video 7, ATI, Ahead, NCR, or Tseng Labs chipsets.



       6           Copyright (c) 1990-1994 Handmade Software, Inc. 

                             Supported 8514/A boards include IBM and those with
                             the Western Digital chipset.

                             Supported XGA boards include those from IBM.


       Math co-processor     A math co-processor will increase the spead of
                             raster scaling types c and d.

       Packing list          The enclosed diskettes contain the following
                             files:

                                  INSTALL.EXE  The Image Alchemy installation
                                               program.


                                  ALCHEMY.EXE  The Image Alchemy software.


                                  GUI.EXE      The Image Alchemy graphical-
                                               user-interface (menu system).


                                  READ.ME      A text document describing any
                                               last minute revisions.


                                  \SAMPLES     A directory containing sample
                                               data files and images.  See the
                                               READ.ME2 file in this directory
                                               for further information.


       Environment           Alchemy uses several different environment
       variables and         variables to determine its behavior.  These
       config.sys            control, among other things, how Image Alchemy
                             uses extended or expanded memory, which display
                             resolutions are available for image viewing, and
                             where temporary files are stored.

                    path     You must either add c:\alchemy to your path, copy
                             the alchemy.exe file to a directory which is
                             already in your path, or be in the c:\alchemy
                             directory when executing Alchemy.












                   Copyright (c) 1990-1994 Handmade Software, Inc.            7 

          Temporary disk     Alchemy uses the environment variable TMP to
                   files     determine where to open its temporary files.  If
                             you have a big enough RAM drive you may want to
                             specify it using the TMP variable.  Be aware that
                             Alchemy needs up to 4 times as much space on that
                             drive as the size of the image (a 640 by 480 image
                             requires up to 1.2 megabytes).

                             An example of setting the TMP variable to the
                             \temp directory on drive e: would be set
                             TMP=e:\temp.

         Use of extended     If there is enough extended or expanded memory
            and expanded     available, Alchemy will use it instead of some of
                  memory     the temporary files it would otherwise use during
                             some conversions.  To use extended memory you must
                             have an XMS driver installed in the config.sys
                             file (such as HIMEM.SYS, QEMM, or 386MAX). To use
                             expanded memory you must have a LIM 3.2 or LIM 4.0
                             expanded memory driver installed (such as EMM386,
                             QEMM, or 386MAX).


                             Alchemy's use of extended/expanded memory can be
                             disabled.  To disable the use of extended and
                             expanded memory, set the environment variable
                             alchemy to x (type set alchemy=x at the DOS
                             prompt).


                             The availability of extended or expanded memory
                             will not allow you to convert larger images, it
                             will just increase the speed of conversions.  If
                             you need to convert very large images contact us
                             about upgrading to Alchemy/386, the 386 Enhanced
                             version of Image Alchemy.

            Checking for     Alchemy will normally check to determine if there
           8514/A boards     is an 8514/A board installed in the computer when
                             viewing images.  However, this can interfere with
                             some network boards, as they use the same I/O
                             addresses that 8514/A boards use.  To disable
                             8514/A checking, set the environment variable
                             alchemy to 8 (type set alchemy=8 at the DOS
                             prompt).


                             Note that this can be combined with other options;
                             for example, to disable both 8514/A checking and
                             extended/expanded memory usage, use
                             set alchemy=8x.





       8           Copyright (c) 1990-1994 Handmade Software, Inc. 

        Limiting maximum     Alchemy will automatically choose the lowest
                 display     resolution which will fit the entire image when
              resolution     viewing images without specifying a display
                             resolution with a VESA compatible SVGA board.
                             However, depending on the monitor and SVGA board
                             combination you have, this can be bad since the
                             monitor may not support the particular resolution
                             the SVGA board is trying to switch to.  To avoid
                             this problem, the environment variable alchemy may
                             be set to indicate the maximum display resolution
                             which Alchemy should use.  Set the alchemy
                             variable to the highest horizontal resolution
                             which your monitor is capable of.  Valid values
                             are 1280, 1024, 800, and 640.  For example, type
                             set alchemy=800 at the DOS prompt if your monitor
                             only supports 640x480 mode and 800x600 mode.

       Combining options     To disable extended/expanded memory usage, and
                             limit the viewing resolution to 640x480 use
                             set alchemy=x640.




































                   Copyright (c) 1990-1994 Handmade Software, Inc.            9 

       UNIX Installation
       ------------------------------------------------------------------------


       Required              At a minimum you must have the following hardware
       equipment             to run Image Alchemy.

              Disk space     A hard drive with at least 2 megaybtes of free
                             space for the Alchemy software and four times as
                             much free space as the size of the image being
                             converted (i.e. a 640x480 image will require up to
                             1.2 megabytes of free space).



       Packing list          The enclosed diskette or tape is in tar format and
                             contains the following files:


                                  alchemy      The Alchemy software.

                                  read.me      A text document describing any
                                               last minute revisions.

                                  /samples     A directory containing sample
                                               data files and images.  See the
                                               read.me2 file in this directory
                                               for further information.



       Environment           Alchemy uses an environment variable to determine
       variable usage        where to place temporary files.

                    path     You must either add $HOME/alchemy to your path,
                             copy the file alchemy to a directory which is
                             already in your path, or be in the $HOME/alchemy
                             directory when executing Alchemy.

          Temporary disk     Alchemy uses the environment variable TMPDIR to
                   files     determine where to put its temporary files.  This
                             is usually set to /usr/tmp or /tmp, but if you are
                             converting very large images there may not be
                             enough space available in the partition those
                             directories are on (for example, converting a
                             10000 x 10000 pixel 24 bit colour image can
                             require up to 300 megabytes of free disk space for
                             temporary file storage).








       10          Copyright (c) 1990-1994 Handmade Software, Inc. 

                             If there is not enough space in the usual TMPDIR
                             directory you will need to set the environment
                             variable TMPDIR to a directory on a different
                             partition.  For example, to set the temporary file
                             directory to the directory /home/images use setenv
                             TMPDIR /home/images.

                             Contact your system administrator if you have
                             problems with Alchemy running out of disk space
                             while converting images.

       Differences           The UNIX and MS-DOS versions of Image Alchemy are
       between UNIX and      very similar.  However, there are several
       MS-DOS                important differences between the two versions:

               Pathnames     Because the MS-DOS and UNIX operating systems use
                             different conventions for path names, users of
                             UNIX will have to substitute forward slashes, "/",
                             for the back slashes, "\", found in the examples
                             in this manual.



           Unintentional     UNIX users should also be aware that the UNIX
                wildcard     shell they are using may be performing wildcard
               expansion     expansion on certain characters (generally "*" and
                             "?").  Since these are options which Alchemy uses,
                             they need to be escaped to prevent the wildcard
                             substitution.  This is done by using a back slash,
                             "\", before the character (so -? becomes -\?).

          Sending output     Several of the examples show output being sent
             directly to     directly to a device (for example prn:).  UNIX
                 devices     users cannot send output directly to a device
                             using Image Alchemy and should substitute a file
                             name for the output device name.

          Viewing images     The UNIX command line version of Image Alchemy
                             does not support image viewing at this time.  We
                             do have an OpenLook version of Image Alchemy
                             available for Sun SPARC workstations, and are
                             working on Motif versions for other workstations.
                             Please contact us for information on the
                             availability of these versions or upgrading .












                   Copyright (c) 1990-1994 Handmade Software, Inc.           11 

























































       12          Copyright (c) 1990-1994 Handmade Software, Inc. 

                                                                              2



       Introduction
       ------------------------------------------------------------------------


       Introduction          Image Alchemy is a command-line driven program.

       Basic                 The basic Image Alchemy usage instructions are:
       instructions
                                alchemy inputFileName [outputFileName]  [output
                                PathName] -options ...

                 Options     Options are the commands that you give Alchemy so
                             that it knows what you want it to do.  So that
                             Alchemy can distinguish between options and file
                             names on the command line, options are preceded by
                             a dash ("-").


                             The only option that is required is the output
                             file format.  Image Alchemy will make reasonable
                             decisions for all of the other options.


                             Some options take parameters.  The parameters may
                             immediately follow the option or be separated by a
                             space.  For example, either -c128 or -c 128 is
                             acceptable.


                             The options themselves are documented in Chapters
                             3 through 8.


                             Note that options can appear anywhere in the
                             command line and usually they can be in any order
                             (certain options take parameters; in those cases
                             the parameters must follow the option).  The case
                             of the options is significant.  For example, -d
                             and -D mean different things.


           InputFileName     The inputFileName is the file name of the existing
                             image file that you are converting from or viewing
                             and must be specified.

                             The inputFileName may include an optional drive
                             and/or path.





                   Copyright (c) 1990-1994 Handmade Software, Inc.           13 

          OutputFileName     The outputFileName is the name of the file you are
                             converting the image to.  The outputFileName is
                             optional;  if it is not specified Alchemy
                             generates one by substituting an appropriate
                             extension to the input file name.

                             If you specify an outputFileName and it does not
                             include an extension one will be added.

                             The outputFileName may include an optional drive
                             and/or path.  If you do not supply a path the
                             current directory will be used as the destination
                             directory.

                             The inputFileName and the outputFileName cannot be
                             the same unless you are writing the output file to
                             a different directory.


          OutputPathName     The outputPathName is the location where you want
                             to put the output that Alchemy will create.  The
                             outputPathName is optional;  if it is not
                             specified Alchemy places the output in the current
                             directory or in the directory specified as part of
                             the outputFileName.

                             Specifying an outputPathName is useful when using
                             the wildcard option to convert multiple files; see
                             the wildcard command below for more information.


       Limitations on        Since Alchemy lets you optionally enter a space
       filenames             between an option and its parameter it is possible
                             to confuse Alchemy if one of the filenames starts
                             with a number.  In particular, if you use an
                             option which has an optional parameter, you choose
                             not to supply the parameter, and you follow that
                             option immediately with a filename which starts
                             with a number, Alchemy doesn't realize that the
                             filename is not the parameter.  While it sounds
                             unlikely that this would ever be a problem it
                             actually happens quite often.



                 Example     If you wanted to convert the file 12.gif to a
                             Targa file with the name output.tga you would have
                             to be careful of the order in which you specified
                             things.


                             If you say

                                alchemy -a 12.gif output.tga


       14          Copyright (c) 1990-1994 Handmade Software, Inc. 

                             Alchemy would misinterpret that as

                                alchemy -a12 .gif output.tga

                             and would generate an error.


                             The easiest way around this problem is to always
                             put the filenames first, such as:

                                alchemy 12.gif output.tga -a

       Output path           The output path name is the location where Alchemy
                             will place its output.

                             While the outputPathName is usually specified on
                             the command line as part of the outputFileName it
                             is useful when using wildcards (and an
                             outputFileName can not be specified).


                 Example     To convert all of the GIF files in the current
                             directory to grayscale and place the results in
                             the \images directory you can use the following
                             command line:

                             alchemy -- *.gif \images -g -b

       Using response        Alchemy can read command line parameters from text
       files                 files (called response files).  Using response
                             files is equivalent to typing the options and/or
                             file names on the command line.  Response files
                             are useful when you have commonly used commands or
                             when you have long commands which would be hard to
                             remember or exceed the command line limits of your
                             operating system.

                             To use a response file you create a text file
                             containing the options and/or file names that you
                             would ordinarily pass to Alchemy on the command
                             line.  You create this text file using a text
                             editor.  This file can have any name or extension
                             you wish.  To pass this file to Alchemy use the @
                             operator, followed immediately by the name of the
                             text file.

                             For example, if you frequently need to scale
                             images to be no larger than 640x480, using 'b'
                             quality scaling, and preserving aspect ratio, you
                             can make a text file which looks like this (called
                             scale, for purposes of this example):

                                -Xb640 -Yb480 -+



                   Copyright (c) 1990-1994 Handmade Software, Inc.           15 

                             You would then use this text file with Alchemy by
                             passing its name along with any other options
                             (including the output file type option and the
                             file names).  For example:

                             alchemy @scale test.gif new.gif -g

                             would convert the GIF file test.gif to a GIF file
                             called new.gif, while performing the desired
                             scaling operation.


                             It is also possible to place filenames of images
                             to convert and other response files in response
                             files.  For example, if you want to convert  the
                             files test1.gif, image.tga, scan1.tif, scan2.tif,
                             and scan3.tif to JPEG files you can create a text
                             which looks like this (called files):

                                test1.gif
                                image.tga
                                scan1.tif
                                scan2.tif
                                scan3.tif

                             And then use this command line to convert those
                             files to JPEG files:

                                alchemy -- @files -j

                             Note the use of the -- option to indicate to
                             Alchemy that more than one filename will be
                             specified.

                             For MS-DOS users it is also possible to place
                             wildcards in response files.  For example, if you
                             want to convert  all of the .gif, .tif, and .tga
                             files to JPEG files you can create a text file
                             which looks like this (called wild):

                                *.gif
                                *.tif
                                *.tga

                             And then use this command line to convert those
                             files to JPEG files:

                                alchemy -- @wild -j

                             UNIX users can accomplish the same task by using
                             ls and redirecting output to a file:

                                ls *.gif *.tif *.tga >wild



       16          Copyright (c) 1990-1994 Handmade Software, Inc. 

                             And then use this command line to convert those
                             files to JPEG files (note the use of the -- option
                             to indicate to Alchemy that you are giving it more
                             than one file to convert):

                                alchemy -- @wild -j

                             If you wanted to scale the images at the same
                             time, using the scale text file created earlier,
                             you would add that response file to the command
                             line.  For example:

                                alchemy -- @files @scale -j

                Comments     A line in a response file which begins with a # is
                             treated as a comment and ignored.

                             Response files may contain commands and filenames
                             on multiple lines and may also contain blank
                             lines.

       Using multiple        Sometimes you may know what you want to accomplish
       runs of Alchemy       but not how to specify the correct combination of
                             options.  For example, you may wish to resize a
                             true colour Targa file that you have scanned and
                             convert it to a 16 colour GIF file.  Let's say
                             that the input file name is file.tga and you want
                             to generate a file with the name file.gif. In this
                             case you could use:

                             alchemy file.tga -Xb640 -Yb480 -c16 -g

                             However, there would be no penalty in quality if
                             you did things in two steps:

                                alchemy file.tga temp.raw -Xb640 -Yb480 -r

                                alchemy temp.raw file.gif -c16 -g

                             In this case you are telling Alchemy to use a
                             temporary raw file called temp.raw.  Except for
                             having to delete the file temp.raw, this would
                             give you identical results to doing things in one
                             step.


                             However, the order of steps is important in many
                             cases.  For example, reversing the order of the
                             two operations in the previous example:

                             alchemy file.tga temp.raw -c16 -g

                                alchemy temp.raw file.gif -Xb640 -Yb480 -g



                   Copyright (c) 1990-1994 Handmade Software, Inc.           17 

                             would give different results.  This is because the
                             scaling operation has to temporarily convert the
                             image to true colour, but the GIF file you are
                             generating has to be paletted, so the second
                             operation would re-dither the image, lowering the
                             quality.


                 Illegal     Sometimes you will have to perform operations
         combinations of     using multiple steps because there are some
                 options     combinations of options that Alchemy explicitly
                             does not allow.  These combinations of options are
                             not allowed because the results would not be what
                             you expect.

                             For example, using the spiff option, -S, in
                             combination with the false colour option, -F,
                             would spiff the image first and then false colour
                             it, which would give the same results as just
                             using the false colour option.

                             Since this is not the result you would most likely
                             want, Alchemy will complain if you specify both of
                             those options at the same time.  In this case you
                             could false colour the image first, generating a
                             temporary image, and then spiff that image.






























       18          Copyright (c) 1990-1994 Handmade Software, Inc. 

                                                                              3



       The Graphical User Interface (Menus)

       MS-DOS Only
       ------------------------------------------------------------------------


       Introduction          Image Alchemy v1.7 is the first release to
                             incorporate a Graphical User Interface (also
                             referred to as a GUI, pronounced "gooey"),
                             commonly referred to as a menu system. The GUI can
                             make using Alchemy much easier for casual or
                             infrequent users, since the various command-line
                             arguments do not need to be memorized.

                             The GUI is actually a separate program which gets
                             information about the conversion from the user,
                             builds a command line for Alchemy, and then calls
                             the actual Alchemy program.  The GUI will let you
                             view the command line parameters it uses, so that
                             you can learn more about Alchemy itself and the
                             options it requires to perform various
                             conversions.

       Starting the GUI      After installing Image Alchemy (described in
                             Chapter 1), the Alchemy executable as well as the
                             GUI should be on your working drive.  The GUI will
                             be able to find the Alchemy executable as long as
                             it is in either the current directory or the
                             search path.


                             Assuming the path has been correctly set, simply
                             typing 'gui' will start Alchemy's graphical user
                             interface.

       The Main Screen       Upon starting the GUI, the screen will be mostly
                             blank, except for a menu bar across the top of the
                             screen, and two small windows at the bottom
                             informing you of the currently selected input file
                             and the output file type.












                   Copyright (c) 1990-1994 Handmade Software, Inc.           19 

                             If you have a mouse connected to your system, you
                             can point-and-click through the menuing system,
                             rather than using the keyboard.  Clicking an entry
                             on the menu bar will pull down that menu, and then
                             clicking on a specific option will actually choose
                             it.

                             Alternatively, you can move the mouse cursor to
                             the menu bar, click on a sub-menu category like
                             File, and while continuing to hold down the mouse
                             button, select a specific item.  When you release
                             the mouse button, that item will be chosen.

                             To access the pull-down menu system using the
                             keyboard, type Alt-?, where ? is the first
                             character of the option.  For example, typing Alt-
                             F will bring down the File sub-menu, and Alt-D
                             will bring down the Dither sub-menu.



                             Pressing and releasing the ALT key by itself will
                             take you up to the menu bar and pull down the
                             first entry (the File sub-menu).  The left and
                             right arrow keys will move between the various
                             sub-menus.  At this point, the up and down arrow
                             keys can be used to highlight a specific option;
                             pressing Return will select that option.


                             While in the menu system, pressing ESC will close
                             the current menu; if you are being prompted for a
                             value in a dialog box, ESC will abort the input,
                             and retain the old value.


                             As you move through various options in the sub-
                             menus, a short help message will appear on the
                             bottom status line, giving you further information
                             on the option you currently have selected.


                             Note that some sub-menu entries may be dimmed;
                             this means that these options cannot be used at
                             this time.  This usually applies to the viewing
                             and conversion commands, which cannot be chosen
                             without first selecting an input file.









       20          Copyright (c) 1990-1994 Handmade Software, Inc. 

       Quitting the GUI      To exit the GUI, select Quit from the File sub-
                             menu.  Alternatively, ALT-X or ALT-F4 will
                             immediately quit the GUI without going through the
                             menu system.



       The File
       Sub-Menu


            Select Input     Choosing this option will bring up a listing of
                   Image     all the files in the current directory.  Using
                             either the keyboard or the mouse, you can select
                             the input file which Alchemy will work on.  There
                             are also listings for the parent directory and
                             various subdirectories (if any), which allow you
                             to move around on the drive.


                             Clicking on the Cancel button or hitting ESC will
                             abort the selection process, keeping the previous
                             input file name.


                             Note that the GUI does not check to make sure that
                             the file you have selected is a valid image file
                             (it would slow the GUI down too much to have to
                             open each file as you highlight it).  As such, it
                             is possible for you to select a file which Alchemy
                             itself will not recognize when a conversion or
                             view is requested.

           Select Output     Selecting the Output Type will display a scrolling
                    Type     window containing the different image formats to
                             which Alchemy can output.  The up and down arrow
                             keys will move the highlight bar up and down one
                             item, and the PgUp and PgDn keys will move the
                             highlight bar up and down one page.  Pressing
                             Return selects the highlighted output type.  The
                             mouse can also be used to scroll through the
                             window; clicking on the up and down arrows will
                             move the highlight bar up and down one entry, and
                             clicking in the scroll bar above or below the
                             current location marker will page up and down
                             through the list.










                   Copyright (c) 1990-1994 Handmade Software, Inc.           21 

                             If you select an output format that has further
                             options (such as compression type), a second pop-
                             up menu will ask you to pick an option.  Either
                             typing the highlighted key or clicking on the name
                             will select that option.

                             For more information on the output types
                             available, and the options that each has, see
                             Chapter 6.

             Image Stats     After selecting an input file, selecting this
                             option will display various information for that
                             file, including the height and width, number of
                             colours, and compression ratio.  Other values may
                             be displayed, if they are available, such as dots
                             per inch (DPI), aspect ratio, and gamma.


                 Viewing     The next four options are for viewing the image
                             you have selected.  See Chapter 9 for more
                             information on the type of SVGA cards supported
                             and details of the viewing commands.


                             View Image will do a standard 8-bit view on an
                             SVGA monitor, displaying only the center portion
                             of the image if it exceeds maximum screen
                             resolution.


                             Using the View Scaled option will work similarly,
                             except it will use Nearest Neighbor scaling to
                             make sure the entire image fits on the screen.



                             If you have an SVGA board and monitor capable of
                             displaying images in true colour (15-, 16-, or 24-
                             bits), select View True Color to take advantage of
                             this.  This option will try to view in the highest
                             resolution possible, while displaying as much of
                             the image as possible.


                             If you have an image larger than what your
                             card/monitor can display in true colour, using the
                             View True Color Scaled option will scale the image
                             so you can view the entire image in true colour.

       Show Command Line     Choosing this option will display the parameters
                             which will actually be passed to Alchemy if the
                             Convert! entry is chosen.  This allows you to see
                             what parameters need to be passed to Alchemy on
                             the command line to enable various options.


       22          Copyright (c) 1990-1994 Handmade Software, Inc. 

            Basic/Expert     This menu entry will change, depending on the
                   Menus     current status of the menu system.  When first
                             started, the GUI will default to Basic mode, which
                             will hide many of the more obscure options Alchemy
                             deals with.  Choosing this option will then force
                             the GUI to use the full, more advanced menus which
                             include all possible options.



                             When the Expert menus are being used, choosing
                             this option will switch back to the Basic menu
                             system.

                Convert!     This should be the last option you select when
                             converting an image; use it only after you have
                             selected all the options you need from the various
                             other menus.


                             After choosing this option, you will be prompted
                             for an output filename, with a default given based
                             on the output type chosen.  To accept this
                             filename, simply press Return.  You may of course
                             modify the default by typing different names,
                             drives, or directories.


                             The GUI will then generate a command line and run
                             the Alchemy software, passing along information
                             about the various options you have selected in the
                             menu.

                             A progress dialog box will keep you informed of
                             the status of the conversion.  After the
                             conversion you will be returned to the main
                             screen.  If the conversion generates an error it
                             will be displayed in a dialog box.

                    Quit     This option will end your GUI session, and return
                             you to the DOS prompt.

       The Resize            The options in this sub-menu allow you to control
       Sub-Menu              various aspects of the output image concerning its
                             size and DPI information.  Along with being able
                             to specify a certain image size, you can also tell
                             Alchemy to make an image larger or smaller by some
                             factor.  Finally, you can specify the aspect ratio
                             and DPI information from within this menu.

                             For further information about the scaling options,
                             see Chapter 9.




                   Copyright (c) 1990-1994 Handmade Software, Inc.           23 

       The Palette Sub-      The entries in the palette sub-menu allow you to
       Menu                  control various aspects of the palette and its
                             generation, including using Heckbert's algorithm,
                             a uniform palette, or a black and white/grayscale
                             palette.  You can also tell Alchemy to use a
                             palette from another image, or use an undercolour
                             removal file during the conversion process.

                             For further information about these topics, see
                             Chapter 8.

       The Colors            The colors sub-menu primarily allows you to
       Sub-Menu              specify the number of colours to be used in the
                             output file.  You can also generate a photographic
                             negative of an image, as well as spiff it using
                             one of three different algorithms.  Finally, from
                             within this sub-menu, you can modify the input,
                             output, and palette gamma values.

                             For further information about the colors options,
                             see Chapter 8.

       The Dither            The dither menu allows you to select the
       Sub-Menu              particular dithering algorithm to use.  You can
                             also specify whether you want a serpentine raster
                             or some amount of perturbation; both of these
                             options help break up visible patterns left by the
                             dithering.


                             For further information about the dithering
                             options, see Chapter 8.
























       24          Copyright (c) 1990-1994 Handmade Software, Inc. 

                                                                              4



       Output Options
       ------------------------------------------------------------------------


       Introduction          The one option which is always required when
                             running Image Alchemy is the output image file
                             type.  Even if you are just re-sizing an image, or
                             changing the number of colours in an image,
                             Alchemy needs to know what type of image you want
                             to create.


                             The file types that Image Alchemy supports are
                             listed below.  In addition to the syntax required
                             to generate the file, any known restrictions or
                             limitations are listed.  If you have trouble
                             reading an image in one of the file formats we
                             claim to support please contact us (see Appendix
                             D, Customer Support).



                             The output option consists of a single letter,
                             followed by any options needed for the file format
                             you are writing.  The output option, like all
                             Alchemy options, is preceded by a dash, "-".  The
                             less common output options consist of a letter
                             preceded by two dashes, "--".

       Output variations     Some of the output formats have several
                             variations; in those cases you specify which
                             variation you want with an optional letter and/or
                             number after the output option.



                 Example     The option to generate a Windows Bitmap file is -
                             w.  There are two types of Bitmap files:
                             uncompressed and Run-Length-Encoded (RLE).  To
                             write out an uncompressed Bitmap file use -w0; to
                             write out an RLE Bitmap file use -w1 (the default
                             Bitmap file is uncompressed, so a -w without any
                             parameter following it would also generate an
                             uncompressed Bitmap file).  Note that Alchemy
                             allows spaces between the option and parameter, so
                             typing -w 1 would be the same as -w1.


        Other variations     Be aware that the other options specified on the
                             command line may also affect the type of file that
                             is generated.

                   Copyright (c) 1990-1994 Handmade Software, Inc.           25 

                 Example     Within the Windows Bitmap file type there are 1
                             bit, 4 bit, 8 bit, and 24 bit files.


                             Alchemy always generates a file using the best
                             match of the file type and the output image.  So,
                             in the case of Windows Bitmap files, if the output
                             image is black and white a 1 bit file is
                             generated.  If the output image is paletted with
                             16 colours or less a 4 bit file is generated.  If
                             the output image is paletted with more than 16
                             colours an 8 bit file is generated.  And if the
                             output image is true colour a 24 bit file is
                             generated.


                             You can explicitly force any of these file types
                             by using other Alchemy options.  For example, if
                             you wanted a 1 bit Windows Bitmap file you would
                             specify -c2 -b -w.  To force a 4 bit file use
                             -c16 -w.  To force an 8 bit file use -c256 -w.
                             And to force a true colour file use -24 -w.


       Identifying image     Image Alchemy identifies the type of file being
       files                 read by checking various magic numbers and other
                             information that varies from format to format.
                             Unfortunately, some formats do not have a magic
                             number; in those cases Alchemy uses other
                             information to guess as to the image type.  It is
                             possible for Image Alchemy to incorrectly identify
                             an image; if this happens you can use the -=
                             option to force Alchemy to recognize the file as a
                             particular format (see Chapter 7 for more
                             information on the -= option)

       MacBinary             When reading images, Alchemy automatically
                             recognizes and reads MacBinary II files (MacBinary
                             files are generated when you accidentally leave
                             MacBinary mode on when transferring a file from a
                             Macintosh).

       Other information     Alchemy will preserve as much information in each
                             file as practical; this always includes the height
                             and width of the image and the number of colours
                             in the image.  Some file types include other data,
                             such as the name of the image, the aspect ratio of
                             the image, the date the image was created, etc.
                             Since most of these items are only supported by a
                             few file formats, Alchemy discards everything but
                             the height, width, number of colours, gamma,
                             aspect ratio, and resolution values.




       26          Copyright (c) 1990-1994 Handmade Software, Inc. 

       Output Options        The individual output options supported by Alchemy
                             are described in alphabetical order on the
                             following pages.  The descriptions follow the
                             template given overleaf.




















































                   Copyright (c) 1990-1994 Handmade Software, Inc.           27 

       Name of format                                                 -option


                             Overview of file format.

       Syntax                Description of syntax.

       Parameters            Brief description of the parameters.  Those
                             parameters which require a detailed explanation
                             are further documented under the comments section
                             below.

       Extensions            The extensions commonly used for this image
                             format.  When multiple extensions are listed
                             Alchemy writes files using the first one, but will
                             check for files using all extensions (in the order
                             listed).  Some formats use more than one file per
                             image, in that case the extension for each piece
                             of the image is listed.  Four letter extensions
                             are skipped on MS-DOS systems.

       Creator               The company or individual who created this image
                             format.  Please contact them for more information
                             on the format.

       Used by               Programs or types of software that use this image
                             format.

       Variations            A list of the variations supported by Image
                             Alchemy.

       Limitations           Any known limitations that Image Alchemy has when
                             reading or writing this image format.

       Comments              Miscellaneous things of which you should be aware.

       Related options       Other Alchemy options that affect the reading or
                             writing of this image format.  Note that -8, -24
                             (and, for some formats, -15, -16, and -32), -c,
                             and -b options have an effect for most image
                             formats and are not listed explicitly.

       Examples              Sample conversions involving this image format.













       28          Copyright (c) 1990-1994 Handmade Software, Inc. 

       ADEX                                                               --A


                             ADEX files are used by the ADEX Corporation
                             ChromaGraph series of graphics cards.

       Syntax                --A compressionType

       Parameter             compressionType:
                                  0:None
                                  1:Run Length Coded
                             The default is None.

       Extensions            .img
                             .rle

       Creator               ADEX Corporation

       Used by               ADEX ChromaGraph cards.

       Variations            4 bit and 8 bit images.

       Comments              Some ADEX files don't contain a palette; in those
                             cases there's usually a second ADEX file which
                             contains the palette to be used.  To read those
                             images that don't have palettes, use the -F false
                             colour option to read the palette from a separate
                             file.

       Related options       -F   False colour

       Example               Convert the file test.gif to an uncompressed ADEX
                             file called test.img:

                                alchemy test.gif --A





















                   Copyright (c) 1990-1994 Handmade Software, Inc.           29 

       Adobe Acrobat PDF                                                  --d


                             Adobe Acrobat PDF (Portable Document Format) files
                             are used by Adobe Acrobat.

       Syntax                --d compressionType

       Parameter             compressionType:
                                  0:None
                                  1:Run Length
                                  2:LZW
                                  3:CCITT Group 3 fax
                                  4:CCITT Group 4 fax
                                  5:JPEG Low Quality
                                  6:JPEG Medium Quality
                                  7:JPEG High Quality
                             The default is None.

       Extension             .pdf

       Creator               Adobe Systems Incorporated

       Used by               Adobe Acrobat.

       Variations            Writes 1 bit black and white, 8 bit grayscale, 8
                             bit paletted, and 24 bit colour images.

       Limitations           Adobe Acrobat files can only be written, not read.

                             CCITT Group 3 fax and Group 4 fax files are always
                             1 bit, black and white.  Selecting either
                             compression type will cause Alchemy to
                             automatically convert the input image to black and
                             white.

       Comments              Alchemy always writes a single page PDF file; this
                             will be changed in a future release.

       Example               Convert the JPEG file sample.jpg to a Run Length
                             compressed PDF file:

                                alchemy sample.jpg --d 1













       30          Copyright (c) 1990-1994 Handmade Software, Inc. 

       Alpha Microsystems BMP                                              -M


                             Alpha Microsystems BMP files are used by Alpha
                             Microsystems.

       Syntax                -M compressionType

       Parameter             compressionType:
                                  0:None
                                  1:Packed
                             The default is None.

       Extension             .bmp

       Creator               Alpha Microsystems

       Used by               Alpha Microsystems workstations.

       Variations            Reads and writes 1, 4, 8, and 24 bit unpacked and
                             packed (run-length encoded) RGB images.

       Limitations           Reading and writing HLS images is not supported.

       Comments              When reading an image without a palette Alchemy
                             will assume the image is gray-scale.

       Examples              Convert the GIF file, bigpict.gif, to an
                             uncompressed Alpha Microsystems BMP file:

                                alchemy bigpict.gif -M

                             Do the same thing, but force a 24 bit image, and
                             compress the image:

                                alchemy bigpict.gif -M1 -24




















                   Copyright (c) 1990-1994 Handmade Software, Inc.           31 

       Autologic                                                          --a


                             Autologic files are black and white or gray-scale
                             files for use with Autologic typesetting
                             equipment.

       Syntax                --a

       Extensions            .gm
                             .gm2
                             .gm4

       Creator               Autologic, Incorporated

       Used by               Autologic typesetting equipment.

       Variations            Graphics modes 2 (black/white) and 4 (gray-scale)
                             are supported.

       Limitations           Only the High Speed Interface inline format is
                             supported.

                             When reading, images must be preceded by a
                             Graphics Parameter Block.

       Examples              Convert the file input.tif to a GM4 file called
                             output.gm4:

                                alchemy input.tif output.gm4 --a -b

                             Convert the file input.tif to a GM2 file called
                             output.gm2:

                                alchemy input.tif output.gm2 --a -b -c2





















       32          Copyright (c) 1990-1994 Handmade Software, Inc. 

       AVHRR                                                              --R


                             AVHRR files are used for satellite image data.

       Syntax                --R outputType

       Parameter             outputType
                                  1:IDIDAS Uncompressed
                                  2:IDIDAS Compressed type 1
                             The default is 1 (IDIDAS Uncompressed).

       Extension             .sst

       Creators              National Oceanic and Atmospheric Administration
                             (NOAA)
                             National Environmental Satellite Data Information
                             Service (NESDIS)

       Used by               IDIDAS
                             SSTMAP
                             IMGMAP

       Variations            Reads 8 and 11 bits per pixel IDIDAS AVHRR files.

                             Writes 11 bits per pixel IDIDAS AVHRR files.

       Limitations           Level 1B AVHRR files will be supported at a later
                             date; please contact us for more information.


                             Alchemy discards all but the top 8 bits when
                             reading 11 bit AVHRR files.  When writing, the
                             bottom 3 bits are set to 0.


                             Any graphics information is discarded when reading
                             the file.


                             Since AVHRR images are always grayscale, Alchemy
                             assumes the use of the -b and -8 options when
                             writing an AVHRR file.

       Comments              AVHRR images contain a lot of information which is
                             not part of the image data.  This information
                             includes the time and date the image was captured,
                             the satellite which captured the image, the type
                             of instrumentation used, etc.  When reading AVHRR
                             images this information is discarded; when writing
                             AVHRR images 0 is written for all values for which
                             data is unavailable.




                   Copyright (c) 1990-1994 Handmade Software, Inc.           33 

       Example               Convert the GOES file, florida.goe, to an
                             uncompressed IDIDAS AVHRR file:

                                alchemy florida.goe --R1




















































       34          Copyright (c) 1990-1994 Handmade Software, Inc. 

       Binary Information Files (BIF)                                      -B


                             There are quite a few programs which produce image
                             files which contain just pixel data.  These image
                             files do not have a header and hence do not
                             include enough information to allow Alchemy to
                             read them.

                             BIF files are a method which can be used to allow
                             Alchemy to read these images.  BIF files can also
                             be created to allow images to be read by software
                             which expects images to be just pixels.  Since
                             required information, such as the height and width
                             of the image, are not present in these files - you
                             must supply it.

                             See Appendix E, "Binary Information Files", for
                             more information.

       Syntax                -B

       Extensions            .bif For ASCII file describing image.
                             .raw For actual image data.

       Creator               Handmade Software, Inc.

       Used by               Image Alchemy
                             Various image processing software

       Variations            24 bit true colour, 8 bit gray-scale, and 1 bit
                             black and white.

       Limitations           Paletted files cannot be read in (a work around is
                             to generate a .PAL file and then false colour the
                             gray-scale image using the -F option).

       Comments              BIF files are used to read and write files which
                             consist entirely of image data.  You have to
                             generate a text file which describes the format of
                             the data you are trying to read in.  This file is
                             called a BIF file.  The format of BIF files is
                             documented in Appendix E, Binary Information
                             Files.  You then instruct Alchemy to read the
                             image data by giving it the name of the .BIF file.

       Related options       -F   False colour

       Examples              Convert the file data to a GIF file:

                                alchemy data.bif -g





                   Copyright (c) 1990-1994 Handmade Software, Inc.           35 

                             Convert the image helen.pcx to a Binary file (this
                             will create two files:  helen.raw and helen.bif):

                                alchemy helen.pcx -B




















































       36          Copyright (c) 1990-1994 Handmade Software, Inc. 

       Calcomp CCRF                                                       --l


                             Calcomp raster files are used by Calcomp thermal
                             transfer and electrostatic printers.

       Syntax                --l type (lower case l)

       Parameter             type:
                                 Thermal Transfer Printer:
                                  0:Uncompressed
                                  1:White Space Suppression
                                  2:Run Length Compression
                                 Electrostatic plotter (CCRF):
                                  6:8 bit bytes, 8 bit compression units
                                  7:8 bit bytes, 16 bit compression units
                                  8:8 bit bytes, 32 bit compression units
                             The default is Thermal transfer, uncompressed.

       Extensions            .crf
                             .ccrf
                             .prn

       Creator               Calcomp

       Used by               Calcomp thermal printers and Electrostatic
                             plotters.

       Variations            Black and white or 1-bit CMYK.

       Comments              If there is only black and white data in the
                             image, a 1 bit file will be generated.


                             For colour images, the black plane will be omitted
                             if it is empty.  See Appendix G for information on
                             how undercolour removal files control the black
                             content of an image.


                             Since the Calcomp CCRF format is a 1-bit CMYK
                             format you may want to use an undercolour removal
                             file when converting a colour image to this
                             format.  See the -C option in Chapter 8 for more
                             information.

       Related options       -C   Undercolour removal
                             -_   Offset image

       Example               Convert the Targa file image1.tga to a CCRF file
                             using 16 bit compression units:

                             alchemy page1.tif --l7



                   Copyright (c) 1990-1994 Handmade Software, Inc.           37 

       CALS                                                               --c


                             Computer-aided Acquisition and Logistics Support
                             (CALS) files are black and white images used by
                             the US Government as part of their transition to
                             electronic media.

       Syntax                --c

       Extension             .cal

       Creator               Defense Logistics Agency (DLA)

       Used by               Department of Defense (DoD)

       Variations            Reads and writes type 1 (Group 4 raster) CALS
                             images.

       Limitations           Document labels, such as document ID and figure
                             ID, are ignored.

       Comments              Since CALS files are always black and white,
                             Alchemy assumes the use of the -b, -8, and -c2
                             options when writing CALS files.


                             CALS images are Fax Group IV compressed and are
                             therefore a good way of storing black and white
                             line drawings and scans.

       Example               Convert the TIFF file page1.tif to a CALS file:

                                alchemy page1.tif --c






















       38          Copyright (c) 1990-1994 Handmade Software, Inc. 

       Core IDC                                                           --B


                             Core IDC files are used by Core Software's GIS
                             software.

       Syntax                --B

       Extension             .idc

       Creator               Core Software Technology

       Used by               Core Software Technology

       Variations            Reads and writes 1 and 3 band files.

                             Reads and writes 8 bit files.

       Limitations           Only 8 bit images can be read.

                             Alchemy cannot read 2 channel or 4 or more channel
                             images without using the -Z option (see the
                             comments section below for more information).

       Comments              1 band files are read in as gray-scale images.

                             3 band files are read in as true colour images.
                             The default colour mapping between RGB and bands
                             1, 2, and 3 is Red=Band 1, Green=Band 2, and
                             Blue=Band 3, this can be changed by using the -Z
                             option.  See the example section below for
                             details.

                             Using the -Z option it is possible to select a
                             single channel or 3 channels when reading a multi-
                             channel Core IDC image.  To use the -Z option
                             follow it with a single number to indicate which
                             channel is to be read as a grey-scale image or
                             three numbers to indicate which channels are to be
                             read as a 24 bit colour image.  See the example
                             section below for details.

       Examples              Convert the Core IDC file atlanta.idc to a Sun
                             raster file:

                                alchemy atlanta.idc -s

                             Convert the file satellite.image to a Core IDC
                             file.

                                alchemy satellite.image satellite.idc --B





                   Copyright (c) 1990-1994 Handmade Software, Inc.           39 

                             The Core IDC file newyork.idc contains 9 bands,the
                             next examples show various ways to read selected
                             bands out of the image.

                             Convert the first band in the image to a
                             grayscale Sun Raster file.

                                alchemy newyork.idc -Z 1 -s

                             Convert the sixth band in the image to a
                             grayscale Sun Raster file.

                                alchemy newyork.idc -Z 6 -s

                             Convert the image to a  24 bit, colour Sun Raster
                             file, using band 2 as the red channel, band 7 as
                             the green channel, and band 4 as the blue channel.

                                alchemy newyork.idc -Z 2 7 4 -s





































       40          Copyright (c) 1990-1994 Handmade Software, Inc. 

       Cubicomp PictureMaker                                              --P


                             Cubicomp PictureMaker files are used in broadcast-
                             quality three dimensional modeling and animation.

       Syntax                --P type

       Parameter             type:
                                  0:Allow any size image
                                  1:Adjust image size to 512 x 488
                             The default is 0.

       Extension             .r8     Red channel image data
                             .g8     Green channel image data
                             .b8     Blue channel image data
                             .a8     Alpha channel image data [optional]

       Creator               Cubicomp Corp.

       Used by               Cubicomp PictureMaker

       Variations            Reads and writes 24 bit true colour images.

       Limitations           If an alpha channel exists, it will be ignored.


                             8-bit paletted PictureMaker files are unsupported.

       Comments              This format is not the same as IBM Picture Maker.

                             The option for adjusting the image size to 512 x
                             488 is useful because Cubicomp PictureMaker does
                             not work with images which are not of this exact
                             size.  If either the X or Y dimension is larger
                             than 512 or 488, respectively, that dimension will
                             be truncated.  If either dimension is smaller than
                             512 or 488, the image will be padded on the right-
                             hand side or bottom, as necessary, with black.


                             PictureMaker images have either three or four
                             separate files per image:  a red file, a green
                             file, a blue file, and an optional alpha channel
                             file.  When reading or writing a PictureMaker file
                             specify the name of the .r8 file, Alchemy
                             automatically generates the name of the .g8 and
                             .b8 files

                             When writing a PictureMaker file Alchemy will
                             overwrite, without warning, existing .g8 and .b8
                             files.




                   Copyright (c) 1990-1994 Handmade Software, Inc.           41 

       Example               Convert the 24-bit JPEG image stones.jpg to
                             PictureMaker files:

                                alchemy stones.jpg --P




















































       42          Copyright (c) 1990-1994 Handmade Software, Inc. 

       Dr. Halo CUT                                                       --C


                             Dr. Halo CUT files are used by various MS-DOS
                             based paint programs.

       Syntax                --C

       Extension             .pal    Palette and header data
                             .cut    Pixel data

       Creator               Media Cybernetics

       Used by               Dr. HALO III Paint Package
                             HALO Desktop Imager

       Variations            8 bits per pixel

       Comments              Dr. Halo CUT images are actually two files.  You
                             specify the name of the .cut file and Alchemy
                             automatically generates the name of the .pal file.

                             When writing a Dr. Halo CUT file Alchemy will
                             overwrite, without warning, existing .pal files.

       Examples              Convert the image test.pcx to a Dr. Halo CUT file:

                                alchemy test.pcx --C




























                   Copyright (c) 1990-1994 Handmade Software, Inc.           43 

       Encapsulated PostScript (EPS)                                       -e


                             EPS files are a subset of PostScript; they may be
                             included by other PostScript files without
                             requiring that the importing software be able to
                             interpret the file.

       Syntax                -e type

       Parameter             type:
                                0:No preview, Unix newlines
                                1:Device independent preview, Unix newlines
                                2:TIFF preview, Unix newlines

                                10:No preview, Mac newlines
                                11:Device independent preview, Mac newlines
                                12:TIFF preview, Mac newlines

                                20:No preview, MSDOS newlines
                                21:Device independent preview, MSDOS newlines
                                22:TIFF  preview, MSDOS newlines

                                100:No preview, Unix newlines, no showpage
                                101:Device independent preview, Unix newlines,
                             no showpage
                                102:TIFF preview, Unix newlines, no showpage

                                110:No preview, Mac newlines, no showpage
                                111:Device independent preview, Mac newlines,
                             no showpage
                                112:TIFF preview, Mac newlines, no showpage

                                120:No preview, MSDOS newlines, no showpage
                                121:Device independent preview, MSDOS newlines,
                             no showpage
                                122:TIFF preview, MSDOS newlines, no showpage
                             The default is device independent preview with
                             Unix newlines and showpage (type 1).


       Extensions            .epsi
                             .eps
                             .epi

       Creator               Adobe Systems, Inc.

       Used by               PostScript printers

       Variations            Black and White, Gray-scale, and RGB.

       Limitations           Image Alchemy can only write, not read, EPS
                             images; if you are interested in upgrading to
                             Image Alchemy PS, which can read EPS and
                             PostScript images, please contact us.

       44          Copyright (c) 1990-1994 Handmade Software, Inc. 

       Comments              If the output is black and white or gray-scale, it
                             will work with any PostScript device.  If it's
                             colour, then the CMYK extensions or a level 2
                             device is required.

                             EPS files are normally written using the UNIX
                             newline convention.  To write an EPS file with
                             Macintosh newlines, add 10 to the preview type.
                             To write an EPS file with MS-DOS newlines add 20
                             to the preview type.  See below for an example.

                             To omit the showpage from the end of the EPS file
                             add 100 to the preview type.  Some software which
                             imports EPS files does not correctly handle EPS
                             files which contain the showpage.

                             If you are writing an EPS file which you intend to
                             send directly to an EPS output device, such as a
                             printer, you will want to write a type 0 EPS file
                             (No Preview, Unix Newlines, and include the
                             showpage).

       Related options       -_   Offset image

       Examples              Convert the file input.gif to a colour EPS file
                             called input.eps with no preview:

                                alchemy input.gif -e0 -24

                             Convert the file input.gif to a gray-scale EPS
                             file called gray.eps, with a device independent
                             preview:

                             alchemy input.gif gray.eps -e -b

                             Convert the file test.gif to a black and white EPS
                             file called test.eps, with a no preview and MS-DOS
                             newlines:

                             alchemy test.gif gray.eps -e20 -b -c2
















                   Copyright (c) 1990-1994 Handmade Software, Inc.           45 

       ER Mapper Raster                                                   --m


                             ER Mapper files are used by ER Mapper satellite
                             image analysis software.

       Syntax                --m

       Extensions            .ers    Header data
                             .  Pixel data

       Creator               Earth Resource Mapping

       Used by               ER Mapper

       Variations            Reads and writes single channel and 3 channel
                             images.

       Limitations           Alchemy cannot read 2 channel or 4 or more channel
                             images without using the -Z option (see the
                             comments section below for more information).

       Comments              ER Mapper files are actually two files, one with
                             the extension .ers and the other without any
                             extension.  The .ers file contains header
                             information and the non-extensioned file contains
                             the actual image data.  You specify the name of
                             the .ers file and Alchemy automatically generates
                             the name of the other file.

                             When writing an ER Mapper file Alchemy will
                             overwrite, without warning, existing ER Mapper
                             image data files.

                             Using the -Z option it is possible to select a
                             single channel or 3 channels when reading a multi-
                             channel ER Mapper image.  To use the -Z option
                             follow it with a single number to indicate which
                             channel is to be read as a grey-scale image or
                             three numbers to indicate which channels are to be
                             read as a 24 bit colour image.  See the example
                             section below for details.

       Examples              Convert the Sun Raster file earth.ras to an ER
                             Mapper file:

                                alchemy earth.ras --m

                             The ER Mapper file Landsat_TM_year_1991.ers
                             contains 7 bands; the next examples show various
                             ways to read selected bands out of the image.





       46          Copyright (c) 1990-1994 Handmade Software, Inc. 

                             Convert the first band in the image to a
                             grayscale Sun Raster file.

                                alchemy Landsat_TM_year_1991.ers -Z 1 -s

                             Convert the fifth band in the image to a
                             grayscale Sun Raster file.

                                alchemy Landsat_TM_year_1991.ers -Z 5 -s

                             Convert the image to a 24 bit, colour Sun Raster
                             file, using band 2 as the red channel, band 7 as
                             the green channel, and band 3 as the blue channel.

                                alchemy Landsat_TM_year_1991.ers -Z 2 7 3 -s









































                   Copyright (c) 1990-1994 Handmade Software, Inc.           47 

       Erdas LAN/GIS                                                      --e


                             Erdas files are used by Erdas image processing
                             software.

       Syntax                --e

       Extensions            .lan
                             .gis

       Creator               Erdas Inc.

       Used by               Erdas remote sensing software.

       Variations            Reads and writes 1 and 3 band files.

                             Reads 4, 8, and 16 bit files.  Writes 8 bit files.

       Limitations           When writing Erdas files Alchemy does not change
                             the extension depending on the number of bands in
                             the image; according to the specification gray-
                             scale files should have the extension .gis and
                             true colour files should have the extension .lan.
                             Alchemy always uses .lan.

                             Alchemy cannot read 2 channel or 4 or more channel
                             images without using the -Z option (see the
                             comments section below for more information).

       Comments              1 band files are read in as gray-scale images.

                             3 band files are read in as true colour images.
                             The default colour mapping between RGB and bands
                             1, 2, and 3 is Red=Band 1, Green=Band 2, and
                             Blue=Band 3; this can be changed by using the -Z
                             option.  See the example section below for
                             details.

                             Using the -Z option it is possible to select a
                             single channel or 3 channels when reading a multi-
                             channel Erdas image.  To use the -Z option follow
                             it with a single number to indicate which channel
                             is to be read as a grey-scale image or three
                             numbers to indicate which channels are to be read
                             as a 24 bit colour image.  See the example section
                             below for details.

       Examples              Convert the GIS file texas.gis to a Sun raster
                             file:

                                alchemy texas.gis -s




       48          Copyright (c) 1990-1994 Handmade Software, Inc. 

                             Convert the file satellite.image to a GIS file.

                                alchemy satellite.image satellite.gis -b --e

                             The Erdas file miami.gis contains 4 bands; the
                             next examples show various ways to read selected
                             bands out of the image.

                             Convert the first band in the image to a grayscale
                             Sun Raster file.

                                alchemy miami.gis -Z 1 -s

                             Convert the fourth band in the image to a
                             grayscale Sun Raster file.

                                alchemy miami.gis -Z 4 -s

                             Convert the image to a 24 bit, colour Sun Raster
                             file, using band 2 as the red channel, band 1 as
                             the green channel, and band 4 as the blue channel.

                                alchemy miami.gis -Z 2 1 4 -s

































                   Copyright (c) 1990-1994 Handmade Software, Inc.           49 

       First Publisher ART                                                --F


                             First Publisher ART files are black and white
                             images used as clip art by First Publisher.

       Syntax                --F

       Extension             .art

       Creator               Software Publishing Corp.

       Used by               First Publisher

       Variations            Black and white, 1 bit per pixel.

       Comments              Since ART files are always black and white, 1 bit
                             per pixel, Alchemy assumes use of the -c2 and -b
                             options when writing them.

       Examples              Convert the image scan.pcx to a First Publisher
                             ART file:

                                alchemy scan.pcx --F
































       50          Copyright (c) 1990-1994 Handmade Software, Inc. 

       Freedom of Press                                                   --f


                             Freedom of Press is a PostScript interpreter from
                             Custom Applications that converts PostScript files
                             to raster files.  The Freedom of Press format is
                             one of the file types it can create.

       Syntax                --f

       Extension             .fop

       Creator               Custom Applications

       Limitations           Output only.

                             Only CMYK 1 bit per component per pixel supported.

       Comments              Freedom of Press images are actually two files, a
                             data file and an info file.  You specify the name
                             of the data file and Alchemy automatically
                             generates the name of the info file.  The output
                             file is normally output.001, output.002, etc.
                             Alchemy will strip the first part of the name and
                             replace it with 'info', so if you specified an
                             output filename of output.005 there will be
                             another file created called info.005.  If you
                             don't specify an extension, Alchemy will use .fop,
                             so you'll get two files named filename.fop and
                             info.fop.  Alchemy will overwrite info files
                             without warning.


                             Since Freedom of Press images are 1-bit CMYK you
                             may want to use an undercolour removal file when
                             converting a colour image to this format.  See the
                             -C option in Chapter 7 for more information.

       Related options       -C   Undercolour removal

       Example               Convert the file image.tga to a Freedom of Press
                             image called output.003 and info.003, controlling
                             the undercolour removal process using sample.ucr,
                             scaling the image to 2500 pixels across (and
                             scaling proportionately vertically) using nearest
                             neighbor scaling, and conserving memory:

                                alchemy --f -Csample.ucr -X2500 -+ -$ image.tga
                                output.003







                   Copyright (c) 1990-1994 Handmade Software, Inc.           51 

       GEM VDI Image File                                                 --g


                             VDI files are files that were developed by Digital
                             Research for use with GEM.

       Syntax                --g

       Extension             .img

       Creator               Digital Research Inc.

       Used by               GEM

       Variations            Reads 1-8 bit grayscale and 3 and 4 bit colour
                             files.


                             Writes 1, 3, and 4 bit grayscale and 3 and 4 bit
                             colour files.

       Limitations           The support for colour and multiple bit grayscale
                             GEM files is not very universal.  Therefore make
                             sure the application you are using to read the GEM
                             files supports them.


                             Alchemy defaults to writing out a 1 bit, black and
                             white GEM file.  You can explicitly force a 3
                             plane colour file by use of the -c8 option and a 4
                             plane colour file by use of the -c16 option (you
                             may add a -b to write a grayscale file instead of
                             a colour file).

       Comments              Because colour GEM files have only 3 or 4 bits of
                             information and no palette support the quality is
                             generally not very good for scanned images.  The
                             GEM format seems to have been designed for line
                             drawings.

       Examples              Convert the image scan.pcx to a black and white
                             GEM file:

                                alchemy scan.pcx --g

                             Convert the image bigscan.tga to a 640x480, 8
                             colour GEM file, using nearest neighbor scaling
                             and type 2 dithering:

                                alchemy bigscan.tga -c 8 --g -X640
                                  -Y480 -d2





       52          Copyright (c) 1990-1994 Handmade Software, Inc. 

                             Do the same thing but write an 8 shade grayscale
                             file with no dithering:

                                alchemy bigscan.tga -c 8 --g -X640
                                  -Y480 -d -b



















































                   Copyright (c) 1990-1994 Handmade Software, Inc.           53 

       GIF                                                                 -g


                             GIF files were developed by CompuServe as a
                             machine independent image file format.  GIF files
                             are the most popular way of storing 8 bit, scanned
                             or digitized images.  In addition the compression
                             ratio achieved by GIF files is usually better than
                             any other 8 bit format in common use.

       Syntax                -g version

       Parameter             version:
                                  0:GIF87A
                                  1:GIF89A
                             The default is GIF87A.

       Extension             .gif

       Creator               CompuServe, Incorporated

       Used by               CompuServe
                             Everyone

       Variations            Reads 1 through 8 bit GIF87A and GIF89A
                             interleaved and non-interleaved files.

                             Writes 1 through 8 bit GIF87A and GIF89A non-
                             interleaved files.

       Limitations           When reading GIF89A files only the first image in
                             the file is read.  Any text, overlays, pauses,
                             palette changes, etc. are ignored.


                             Because GIF files only store the size of the
                             palette to the nearest power of 2 the exact
                             palette size is lost when converting to and from
                             GIF files.  For example, if you convert a 240
                             colour Sun Raster file to a GIF file and back to a
                             Sun Raster file the resulting Sun Raster file will
                             have 256 colours.

       Comments              GIF89A files are a new variation of GIF files that
                             was introduced in 1990 which allow the inclusion
                             of text and simple animations in GIF files.

                             When writing a file you probably want to use the
                             GIF87A variation, since the GIF89A extensions
                             aren't necessary to store single images and a lot
                             of other software still can't read GIF89A images.
                             The only advantage to GIF89A is that aspect ratio
                             information is preserved (GIF87A does not have a
                             provision for storing aspect ratio).


       54          Copyright (c) 1990-1994 Handmade Software, Inc. 


                             The GIF format includes a field for storing the
                             colour to be used for the background when viewing
                             files.  Alchemy does not make use of this value.
                             Alchemy sets the background colour to the darkest
                             colour in the palette when viewing files and
                             organizes the palette such that the first colour
                             is the darkest colour when writing GIF files, if
                             the palette is created by Alchemy (you can
                             override this by using the -z option).

       Related options       -z   Palette Selection

       Examples              Convert the image test.pcx to a GIF87A image.

                                alchemy test.pcx -g

                             Convert the file input.tga to a 16 colour GIF89A
                             file:

                                alchemy input.tga -c16 -g1



































                   Copyright (c) 1990-1994 Handmade Software, Inc.           55 

       GOES                                                               --G


                             GOES files are used for satellite image data.

       Syntax                --G goesType

       Parameter             goesType:
                                  0:GARS format
                                  1:McIDAS format
                             The default is 0 (GARS format).

       Extension             .goe

       Creators              The University of Wisconsin
                             National Oceanic and Atmospheric Administration
                             (NOAA)
                             National Environmental Satellite Data Information
                             Service (NESDIS)

       Used by               Various satellite image processing software,
                             including the McIDAS system.

       Variations            Reads 8, 16, and 32 bits per pixel GOES images.

                             Writes 8 bits per pixel images.

       Limitations           When reading 16 and 32 bit images Alchemy discards
                             all but the top 8 bits of data.


                             Alchemy discards any calibration data and level
                             maps when reading images.


                             Because of difficulty in getting a sufficient
                             number of test images in the GOES format
                             (especially the PUT format) reading GOES images
                             has not been thoroughly tested.  If you have any
                             GOES images  which Alchemy does not read correctly
                             please contact us.

       Comments              The GARS format is a 7680 bytes per block,
                             Motorola byte-order, EBCDIC format; the MCIDAS
                             format is a continuous data, Intel byte-order,
                             ASCII format.


                             Since GOES images are always grayscale, Alchemy
                             assumes the use of the -b and -8 options when
                             writing a GOES file.





       56          Copyright (c) 1990-1994 Handmade Software, Inc. 

                             GOES images contain a lot of information which is
                             not part of the image data.  This information
                             includes the time and date the image was captured,
                             the satellite which captured the image, the type
                             of instrumentation used, etc.  When reading a GOES
                             image this information is discarded; when writing
                             a GOES image 0 is written for all values for which
                             data is unavailable.

       Examples              Convert the Erdas file, florida.gis, into a GOES
                             GARS image:

                                alchemy florida.gis --G0

                             Do the same thing, but write out a GOES McIDAS
                             image:

                                alchemy florida.gis --G1






































                   Copyright (c) 1990-1994 Handmade Software, Inc.           57 

       Hitachi Raster Format                                              --h


                             Hitachi Raster Format (HRF) files are black and
                             white images used by CADCore.

       Syntax                --h

       Extension             .hrf

       Creator               Hitachi Software Engineering Co., Ltd.

       Used by               Information and Graphics Systems, Inc. (IGS)

       Comments              Since HRF files are always black and white,
                             Alchemy assumes the use of the -b, -8, and -c2
                             options when writing HRF files.


       Example               Convert the TIFF file page1.tif to a HRF file:

                                alchemy page1.tif --h


































       58          Copyright (c) 1990-1994 Handmade Software, Inc. 

       HP Printer Command Language (PCL)                                   -P


                             HP PCL files are used by HP LaserJets and
                             compatible printers.

       Syntax                -P type

       Parameter             type:
                                  0:Uncompressed
                                  1:RLE compressed
                                  2:TIFF compressed
                                  3:Delta Row compressed

                                  10:Landscape, Uncompressed
                                  11:Landscape, RLE compressed
                                  12:Landscape, TIFF compressed
                                  13:Landscape, Delta Row compressed

                                  100:LaserJet 4, Uncompressed
                                  101:LaserJet 4, RLE compressed
                                  102:LaserJet 4, TIFF compressed
                                  103:LaserJet 4, Delta Row compressed

                                  110:LaserJet 4, Landscape, Uncompressed
                                  111:LaserJet 4, Landscape, RLE compressed
                                  112:LaserJet 4, Landscape, TIFF compressed
                                  113:LaserJet 4, Landscape, Delta Row
                             compressed
                             The default is type 0.

       Extension             .pcl

       Creator               Hewlett-Packard Company

       Used by               HP LaserJet printers
                             HP compatible laser printers

       Variations            1 bit per pixel, black and white.


                             Reads and writes uncompressed, RLE compressed,
                             TIFF compressed, and Delta Row Compressed files.

                             Reads and writes portrait and landscape files.

       Limitations           In addition to raster images, PCL files can
                             include text and vector graphics information.
                             When reading Alchemy only pays attention to raster
                             images in the file and attempts to skip everything
                             else.  See Appendix A, Answers to Frequently Asked
                             Questions, for a further discussion of this.




                   Copyright (c) 1990-1994 Handmade Software, Inc.           59 

                             The only resolutions allowed in PCL files are
                             75 DPI, 100 DPI, 150 DPI, and 300 DPI (and, in the
                             case of LaserJet 4 type files, 200 DPI and
                             600 DPI) and the X and Y resolution are the same.


                             If you specify a non-allowable resolution Alchemy
                             automatically alters the resolution to the next
                             higher resolution.  For example, if you specify
                             250 DPI Alchemy will write a 300 DPI PCL file.


                             If no resolution is specified either on the
                             command line or in the input file Alchemy
                             automatically chooses the smallest resolution
                             which will allow the entire image to fit on an
                             8.5" x 11" page.

       Comments              Since PCL files are always 1 bit, black and white
                             files, Alchemy assumes the use of the -b, -c2, and
                             -8 options when writing a PCL file.


                             When converting colour or gray-scale images to PCL
                             you will probably want to scale the output so the
                             image will be larger than the input image.  This
                             will allow the dithering to preserve more detail
                             in the image.




























       60          Copyright (c) 1990-1994 Handmade Software, Inc. 

                             Not all PCL compatible printers can print all
                             types of compressed PCL file.  Specifically,
                             LaserJet II, IID, and earlier printers can print
                             only uncompressed PCL files.  LaserJet IIp
                             printers can print only uncompressed and RLE
                             compressed files.  LaserJet III, IIID, IIIp,
                             IIIsi, and 4 printers can print all types of
                             compressed PCL files.

                             In general, the higher the compression type, the
                             better the compression ratio.

                             The Landscape option can be used to write a
                             landscape PCL file.  Because of changes in the PCL
                             format, only LaserJet III and newer printers will
                             correctly print Alchemy produced landscape PCL
                             files.

                             PCL files can be used to generate output which can
                             be printed on HP LaserJet and compatible printers.
                             The easiest method is to simply generate a .PCL
                             file and then copy it to the printer by using the
                             copy command (when using the copy command from MS-
                             DOS you will have to use a /B to make sure the
                             entire file is copied to the printer; see the
                             example below for more information).

                             For MS-DOS users it is possible to write a PCL
                             file directly to a HP LaserJet or compatible
                             printer.  If you use the name of the device as the
                             output file name Alchemy will redirect output to
                             that device (for example, use prn: as the output
                             file name if your LaserJet is attached to the prn:
                             port) .

                             You may want to adjust the output gamma to
                             compensate for dot gain when generating a PCL file
                             to print on a laser printer.  See Appendix A,
                             Answers to Frequently Asked Questions, for more
                             information on dot gain.

                             The best results are usually achieved with
                             dithering type 3, a serpentine raster, and some
                             dithering noise (use -ds3 10, for example).

       Related options       -_   Offset image

       Examples              Convert the image image.gif to a HP PCL file,
                             using no compression:

                                alchemy image.gif -P





                   Copyright (c) 1990-1994 Handmade Software, Inc.           61 

                             Convert the image small.gif to a HP PCL file
                             called out.pcl with dimensions of 2000 by 2000 at
                             300 DPI, performing gamma correction to compensate
                             for dot gain, and using dithering type 3, with a
                             serpentine raster, and adding dithering noise :

                             alchemy small.gif out -P -X2000 -Y2000
                             -D 300 300 -Gi 1.0 -Go 2.0 -ds3 10

                             Convert the image small.gif to a HP PCL file
                             called out2.pcl with dimensions of 2000 by 2000 at
                             300 DPI, using TIFF compression:

                                alchemy small.gif -P2 -X2000 -Y2000
                                -D 300 300 out2

                             Print the image madonna.gif directly to your
                             LaserJet 4 at the largest resolution, using Delta
                             Row compression with dithering type 22 (printing
                             directly to the printer works only in the MS-DOS
                             version of Alchemy):

                                alchemy madonna.gif prn: -P104 -D600 600 -
                                Xb4800 -YB6600 -+ -d22

                             Print all the TIFF files in the current directory
                             directly to a LaserJet, while scaling them to fill
                             the page:

                                alchemy *.tif prn: -P -D 300 300 -Xb2400 -
                                Yb3000 -+

























       62          Copyright (c) 1990-1994 Handmade Software, Inc. 

       HP Raster Transfer Language (RTL)                                  --r


                             RTL files are used by HP colour raster printers
                             and plotters.

       Syntax                --r type

       Parameter             type:
                                  0:PaintJet, PaintJet 300XL, PaintJet 1200C      
                                     uncompressed
                                  1:650C and HP7600 uncompressed
                                  2:650C and HP7600 TIFF compressed
                                  3:HP7600 planar, uncompressed
                                  4:HP7600 planar, TIFF compressed
                                  5:HP7600 planar, Group III compressed
                                  6:DesignJet 600 and 650C on-the-fly,            
                             uncompressed
                                  7:DesignJet 600 and 650C on-the-fly, TIFF       
                                     compressed
                                  9:PaintJet 300XL and PaintJet 1200C TIFF        
                             compressed
                                  10:NovaJet TIFF compressed
                             The default is Type 2.

       Extension             .rtl

       Creator               Hewlett-Packard Company

       Used by               HP raster plotters and printers including
                             PaintJets, DesignJets, and HP 7600 Series
                             plotters.

                             NovaJet Plotters.

       Variations            CMYK, 1 bit per component per pixel.

                             Black and white, 1 bit per pixel.

       Limitations           Output only.

       Comments              RTL files can be used to produce output which can
                             be printed on HP colour printers and raster
                             plotters.  The file can be printed by sending the
                             file to the plotter.

                             Compression types 6 and 7 are equivalent to types
                             1 and 2 except they tell the plotter it may plot
                             the data as received instead of waiting for the
                             entire image.  This is useful on the DesignJet
                             plotters which have small buffers compared to the
                             imageable area.




                   Copyright (c) 1990-1994 Handmade Software, Inc.           63 

                             The NovaJet option causes Alchemy to create RTL
                             files which are compatible with NovaJet plotters.


                             Alchemy will generate a colour RTL file unless the
                             input file is black and white or grayscale or the
                             -b option is specified as part of the conversion.


                             There is no additional setup required for the
                             PaintJet or DesignJet plotters.

                             HP7600 series plotters should be in HP-GL/2 mode;
                             best results will generally be achieved with
                             compensation off.  To get colour plots from the
                             HP7600 series the plotter must be in 4 or 5 pass
                             mode.


                             If the input is black and white, you can do the
                             conversion without an undercolour removal file and
                             with dithering off.  This will result in a faster
                             conversion.


                             If the input is gray-scale, you probably do want
                             to use an undercolour removal file to perform
                             density correction, but with 100% black removal
                             (the black removal tables should contain 0 through
                             255, increasing by one each line) so that the
                             output won't contain cyan, magenta, or yellow.
                             The sample directory on the distribution diskette
                             has a UCR file called gray.ucr which has 100%
                             black removal.


                             MS-DOS users can send the RTL file directly to the
                             plotter when generating an RTL file of type 0, 1,
                             2, 6, 7, 9, or 10.  To send the file directly give
                             the name of the output device as the output file
                             (for example, if your plotter is connected to your
                             computer via lpt1: specifying lpt1: as the output
                             file will send output directly to that device).

                             Since the HP RTL format is a 1-bit CMYK format you
                             may want to use an undercolour removal file when
                             converting a colour image to this format.  See the
                             -C option in Chapter 8 for more information.

       Related options       -C   Undercolour removal
                             -d   Specify dither type
                             -_   Offset image




       64          Copyright (c) 1990-1994 Handmade Software, Inc. 

       Examples              Convert the black and white image test.wpg to a
                             RTL file for a PaintJet called test.rtl, not using
                             a UCR file and with dithering off:

                                alchemy test.wpg --r0 -d0

                             Convert the file image.tga to a RTL file for a
                             PaintJet called image.rtl, using the undercolour
                             removal file sample.ucr:

                                alchemy image.tga --r0 -Csample.ucr

                             Convert the file image.tga to a planar RTL file
                             called image.rtl using TIFF compression,
                             controlling the undercolour removal process using
                             sample.ucr, scaling the image to 3000 pixels
                             across using good quality scaling, preserving the
                             aspect ratio (by proportionately scaling the image
                             vertically), and conserving memory:

                                alchemy image.tga --r4 -Csample.ucr -Xb3000 -+
                                -$

                             Convert the file image.tga to an RTL file for a
                             DesignJet 650C, sending the image directly to the
                             plotter, using the UCR file sample.ucr, dithering
                             type 3 (with a serpentine raster), and scaling the
                             image to be 17 inches wide and preserving the
                             aspect ratio (the plotter is attached to the lpt1:
                             port of an IBM PC):

                                alchemy image.tga lpt1: --r7 -Csample.ucr -ds3
                                -Xb17i -+























                   Copyright (c) 1990-1994 Handmade Software, Inc.           65 

       HP-48sx Graphic Object (GROB)                                      --H


                             Graphic Object files are used by HP-48sx
                             calculators.

       Syntax                --H type

       Parameter             type:
                                  0:Binary
                                  1:ASCII
                             The default is Binary.

       Extension             .grb
                             .asc

       Creator               Hewlett-Packard Company

       Used by               HP-48sx calculators.

       Variations            Black and white, 1 bit per pixel.

       Comments              Since GROB files are always black and white,
                             Alchemy assumes the use of the -b, -8, and -c2
                             options when writing GROB files.

       Example               Convert the image madonna.gif to a ASCII HP-48sx
                             GROB file

                                alchemy madonna.gif --H 1


























       66          Copyright (c) 1990-1994 Handmade Software, Inc. 

       HSI JPEG                                                           --j


                             The HSI JPEG format is a variation of the JPEG
                             format that was designed by Handmade Software to
                             better compress paletted images.

       Syntax                --j

       Extension             .jpg

       Creator               Handmade Software, Inc.

       Used by               Image Alchemy
                             GIF2JPG (another Handmade Software product)

       Variations            8 bit paletted

       Comments              Paletted images often have large areas where the
                             image consists of 1 or 2 colours; JPEG compression
                             does a poor job on these sections when compared to
                             LZW compression.  HSI JPEG files are a combination
                             of JPEG and LZW compression.

                             HSI JPEG files are not compatible with JPEG or
                             JFIF files.  If you intend to transfer files to
                             other systems do not use this format, use the
                             standard JPEG format instead (using the -j
                             option).

                             If you are interested in adding support for HSI
                             JPEG files to your software please contact us for
                             information on the format.

       Example               Convert the file madonna.gif to an HSI JPEG file:

                                alchemy madonna.gif --j



















                   Copyright (c) 1990-1994 Handmade Software, Inc.           67 

       HSI Palette                                                         -l


                             PAL files are palettes which are ASCII files that
                             can be edited with a text editor.

       Syntax                -l (lower case L)

       Extension             .pal

       Creator               Handmade Software, Inc.

       Used by               Image Alchemy

       Variations            Palette files are always ASCII files.

       Limitations           .PAL files contain only a palette.

       Comments              The format of PAL files is described in
                             Appendix H.

       Related options       -f   Match image to specified palette
                             -F   False colour with specified palette
                             -L   Output Multi-Image Palette

       Examples              Extract the palette from the GIF file madonna.gif:

                                alchemy madonna.gif -l

                             Convert the file image.tga to a GIF file, matching
                             the palette found in standard.pal:

                                alchemy image.tga -g -f standard.pal























       68          Copyright (c) 1990-1994 Handmade Software, Inc. 

       HSI Raw                                                             -r


                             HSI Raw files are used internally by Image Alchemy
                             when converting between certain combinations of
                             image formats.  If you are interested in
                             converting custom format images to be used with
                             Image Alchemy we suggest using HSI Raw Files.

       Syntax                -r

       Extension             .raw

       Creator               Handmade Software Inc.

       Used by               Image Alchemy

       Variations            8 bit paletted and 24 bit true colour,
                             uncompressed, not packed.

       Comments              This format is used internally as temporary files
                             by Alchemy when doing certain image conversions;
                             it can also be explicitly read and written.  This
                             format is described in Appendix F.

       Examples              Convert the file test.lbm to a raw file:

                                alchemy test.lbm -r




























                   Copyright (c) 1990-1994 Handmade Software, Inc.           69 

       IBM Picture Maker                                                  --i


                             IBM Picture Maker files are used by IBM
                             presentation software.

       Syntax                --i

       Extension             .pic

       Creator               IBM Corp.

       Used by               IBM Storyboard Live!

       Variations            Reads and writes 256 colour Picture Maker files.

       Limitations           16 colour Picture Maker files are not supported.

                             Picture Maker images cannot be larger than
                             640x480.

       Comments              This is not the same format as Cubicomp
                             PictureMaker.


                             Picture Maker files may be either 320x200 or
                             640x480.  Image Alchemy will write the smallest
                             variation that the image will fit in, with the
                             image centered and the borders filled with colour
                             0.  If you attempt to write a Picture Maker file
                             which is larger than 640x480 an error is
                             generated.

       Example               Convert the PCX file, giraffe.pcx, into an IBM
                             Picture Maker file:

                                alchemy giraffe.pcx --i



















       70          Copyright (c) 1990-1994 Handmade Software, Inc. 

       IFF/ILBM                                                            -i


                             IFF (Interchange File Format) files are used by
                             Amiga computers for storing a number of types of
                             data, including images, text, and music; ILBM
                             (InterLeaved BitMap) is a type of IFF file used to
                             store images.

       Syntax                -i

       Extensions            .lbm
                             .iff
                             .ilbm

       Creator               Commodore-Amiga Corp.

       Used by               Amiga
                             Deluxe Paint

       Variations            Reads 1 through 8 bit, 24 bit, HAM, and PBM images

                             Writes 1 through 8 bit and 24 bit images.

       Limitations           Dynamic Hi-Res images are not supported.

                             Does not write images in any of the Amiga-specific
                             display modes.

       Comments              If you're writing an ILBM file for use on an
                             Amiga, you probably want to write either a
                             paletted file with 32 colours or a 24 bit file.
                             24 bit ILBM files can then be converted to one of
                             the Amiga-specific display modes with various
                             third-party utilities.

       Example               Convert the file input.pcx to an IFF/ILBM file
                             called output.lbm with 32 colours:

                                alchemy input.pcx output.lbm -i -c32
















                   Copyright (c) 1990-1994 Handmade Software, Inc.           71 

       Img Software Set                                                   --Q


                             The Img Software Set  is a collection of tools for
                             manipulating graphic images freely available for
                             various UNIX workstations.

       Syntax                --Q

       Extensions            .img
                             .p
                             .a

       Creator               Paul Raveling

       Used by               Img Software Set

       Variations            Reads and writes 8 bit paletted and 24 bit images.

       Limitations           Alchemy does not read nor write compressed (.Z)
                             images.  Use the UNIX supplied uncompress program
                             to decompress those images before reading with
                             Alchemy.

       Comments              The Img Software Set is available via anonymous
                             ftp as expo.lcs.mit.edu:contrib/img_1.3.tar.Z or
                             venera.isi.edu:pub/img_1.3.tar.Z or on floppy disk
                             from us.

       Example               Convert the Sun Raster file test.ras to an Img
                             Software Set file:

                                alchemy test.ras --Q























       72          Copyright (c) 1990-1994 Handmade Software, Inc. 

       Jovian VI                                                          --J


                             Jovian VI files are created by the Jovian Logic
                             video capture boards.

       Syntax                --J

       Extensions            .vi

       Creator               Jovian Logic Corp.

       Used by               Jovian Logic

       Variations            Reads 1, 4, 6, and 8 bit gray-scale images, 4 and
                             8 bit paletted images, and 16 and 24 bit true
                             colour images.

                             Writes 8 bit gray-scale, 4 and 8 bit paletted
                             images, and 16 and 24 bit true colour images.

       Limitations           Reads files with 6 and 8 bit palettes, always
                             writes 6 bit palettes.

                             Gray-scale files are always 8 bit.

       Comments              When writing a VI file the palette always starts
                             at 0, but colour 0 will not necessarily be black
                             (this is the way that Jovian VI files are
                             written).

       Example               Convert the GIF file, test.gif, to a 16 colour VI
                             file:

                                alchemy test.gif --J -c16





















                   Copyright (c) 1990-1994 Handmade Software, Inc.           73 

       JPEG/JFIF                                                           -j


                             JPEG is an image file format that uses a lossy
                             compression technique to achieve high compression
                             ratios.  See Appendix C, JPEG Compression, for
                             more information on the JPEG file format.

       Syntax                -j[coding] quality

       Parameters            coding:
                                  Specify the type of entropy coding to
                             perform.
                                     none:default Huffman coding
                                     h:optimum Huffman coding
                             quality:
                                  1 through 100 (larger is higher quality)
                             The default quality is 32.

       Extension             .jpg

       Creator               Joint Photographic Experts Group (JPEG)

       Used by               Lossy compression of photographic images.

       Variations            Gray-scale images are saved as single channel JPEG
                             files; colour images are saved as three channel
                             JPEG files.

                             Reads and writes baseline JPEG with CCIR-601 YCbCr
                             colour space, interleaved components, Huffman
                             coded.

                             Alchemy can read files with any component sub-
                             sampling up to 4x4; it always writes 2h:1v 1h:1v
                             1h:1v.

                             Alchemy JPEG files comply with the industry
                             standard 'JFIF' interchange format.

       Limitations           JPEG files are always lossy, which means that the
                             compressed image is not identical to the original
                             image.  At high quality factors (32 and above)
                             this loss is generally so slight as to be barely
                             noticeable.  There is no quality factor which is
                             guaranteed to be lossless.










       74          Copyright (c) 1990-1994 Handmade Software, Inc. 

       Comments              By default, Image Alchemy uses a fixed set of
                             Huffman tables to compress an image.  If the -j is
                             immediately followed by an 'h', Alchemy will
                             generate a set of custom tables optimized for the
                             image and quality factor.  This usually produces
                             5-20% better compression (depending on the image
                             content and quality factor) but requires an
                             additional pass over the image data, so it takes a
                             little longer to compress (there's no effect on
                             the decompression time).

                             Quality may vary between 1 and 100; the default is
                             32.  The higher the number the higher the quality
                             of the image and the lower the compression ratio.
                             Quality factors below 10 will produce images with
                             significant loss of quality.

                             JPEG files are based on the Joint Photographic
                             Experts Group (JPEG) CD 10918-1 draft standard.

                             Since JPEG compression was designed for use with
                             continuous tone images (such as those produced by
                             a scanner or digitizer), poor results can be
                             expected when compressing line drawings.


       Related options  -q   Apply Smoothing when decompressing a JPEG image.
                             Because JPEG compression works on 8x8 pixel blocks
                             there may be discontinuities at the edges of these
                             blocks producing block artifacts.  Smoothing
                             attempts to reduce these artifacts.  Smoothing is
                             really only necessary at very low quality settings
                             (less than 10); even then the effects of smoothing
                             are not particularly significant.

       Examples              Convert the file photo.tga to a JPEG file called
                             photo.jpg, using a high quality setting:

                             alchemy photo.tga -j70

                             Convert the file photo.tga to a JPEG file called
                             photo.jpg, using a low quality setting and
                             generating optimum Huffman tables:

                                alchemy photo.tga -jh10

                             Convert the JPEG file, lores.jpg, to a PCX file
                             using smoothing:

                                alchemy lores.jpg -p -q






                   Copyright (c) 1990-1994 Handmade Software, Inc.           75 

       Lumena CEL                                                         --L


                             Lumena CEL files are used by Time Arts software.

       Syntax                --L

       Extension             .cel

       Creator               Time Arts

       Used by               Lumena

       Variations            Reads and writes 15 and 32 bit images.

       Limitations           The Alpha channel in 32 bit images is ignored.

       Example               Convert the file test.tga to a Lumena CEL file:

                             alchemy test.tga --L




































       76          Copyright (c) 1990-1994 Handmade Software, Inc. 

       Macintosh PICT/PICT2                                                -m


                             PICT files were created by Apple Computer as a
                             common format for Macintosh applications to use.
                             Virtually every Macintosh application can use PICT
                             files.

       Syntax                -m macBinary

       Parameters            macBinary:
                                  0:Do not write a MacBinary file
                                  1:Write a MacBinary file
                             The default is to not write a MacBinary file.

       Extensions            .pict
                             .pic

       Creator               Apple Computer, Inc.

       Used by               Macintosh computers

       Variations            Reads 1, 2, 4, 8, 16, and 32 bit PICT and PICT2
                             images

                             Writes 1, 2, 4, 8, and 32 bit PICT2 images.

       Limitations           Only pays attention to pixMaps in the image;
                             attempts to skip everything else.

       Comments              Due to the enormous number of options allowed in
                             PICT files, reading PICTs may not always work.
                             See Appendix A, Answers to Frequently Asked
                             Questions, for more information.

                             Adding a MacBinary header to a MacPaint file is
                             useful if transferring the file to a Macintosh
                             computer by modem.  The MacBinary header will
                             allow the Macintosh to automatically recognize the
                             file as a MacPaint file.

       Example               Convert the file input1.gif to a Mac PICT file
                             called input1.pic:

                             alchemy input1.gif -m











                   Copyright (c) 1990-1994 Handmade Software, Inc.           77 

       MacPaint                                                           --t


                             MacPaint files are black and white images used by
                             Macintosh computers.

       Syntax                --t macBinary

       Parameters            macBinary:
                                  0:Do not write a MacBinary file
                                  1:Write a MacBinary file
                             The default is to not write a MacBinary file.

       Extensions            .mac

       Creator               Apple Computer, Inc.

       Used by               Macintosh computers

       Variations            1 bit per pixel, black and white.

       Limitations           MacPaint images are always 576x720 pixels.  If you
                             attempt to write a MacPaint image which is larger,
                             Alchemy will report this as an error.  If you
                             write an image which is smaller Alchemy will pad
                             the image with white space along the right-hand
                             side and bottom.

                             Because MacPaint images are always black and
                             white, the -c2, -8, and -b options are assumed
                             when writing an image.

       Comments              Adding a MacBinary header to a MacPaint file is
                             useful if transferring the file to a Macintosh
                             computer by modem.  The MacBinary header will
                             allow the Macintosh to automatically recognize the
                             file as a MacPaint file.

       Example               Convert the file input1.gif to a MacPaint file
                             called input1.mac:

                                alchemy input1.gif --t














       78          Copyright (c) 1990-1994 Handmade Software, Inc. 

       MTV Ray Tracer                                                     --M


                             MTV files are used by the MTV RayTracer, a public
                             domain ray tracer for Suns and other workstations.

       Syntax                --M

       Extension             .mtv

       Creator               Mark T. VandeWettering

       Used by               MTV Raytracer

       Variations            24 bit true colour.

       Comments              MTV is a public domain ray-tracer available free
                             of charge via anonymous ftp from
                             drizzle.cs.uoregon.edu or via floppy disk from us.

       Example               Convert the file spheres.img to a MTV file:

                                alchemy spheres.img --M

































                   Copyright (c) 1990-1994 Handmade Software, Inc.           79 

       Multi-Image Palette                                                 -L


                             This option will generate an optimum palette for a
                             number of images.  This is useful for finding a
                             common palette where multiple images are used
                             (animations, for instance).

       Syntax                -L filename

       Parameters            filename:
                                  name of the output file to contain the
                             optimized palette

       Extension             .pal

       Creator               Handmade Software, Inc.

       Used by               Image Alchemy

       Variations            Palette files are always ASCII files.

       Limitations           .PAL files contain only a palette.

       Comments              The format of PAL files is described in
                             Appendix H.

                             This output option is unique in that it will cause
                             Alchemy to generate only one output file,
                             independent of how many input files are specified
                             (the other output options generate one output file
                             per input file).  Also the file name of the output
                             file must be specified immediately after the -L
                             option (ordinarily the output file name can appear
                             anywhere on the command line).

       Related options       -f   Match image to specified palette
                             -F   False colour with specified palette
                             -l   Generate a palette file for a single image

       Examples              Generate an optimum palette called final.pal for
                             all GIF files in the current directory:

                             alchemy -- *.gif -L final.pal

                             Now map all the GIF files to that palette, putting
                             the results in a sub-directory call new (the files
                             cannot be placed in the current directory because
                             the file names would conflict with the original
                             image file names):

                                alchemy -- *.gif -f final.pal new\




       80          Copyright (c) 1990-1994 Handmade Software, Inc. 

       OS/2 Bitmap (BMP)                                                   -O


                             OS/2 BMP files are used by IBM OS/2 2.0.

       Syntax                -O compressionType (Uppercase letter o)

       Parameter             compressionType:
                                  0:None
                                  1:RLE
                             The default is none.

       Extension             .bmp

       Creator               IBM Corp.

       Used by               OS/2 2.0

       Variations            Reads 1, 4, 8, and 24 bit RGB (raw), RLE4, and
                             RLE8 files.

                             Writes 1, 4, 8, and 24 bit RGB (raw), RLE4, and
                             RLE8 files.


       Examples              Convert the image test.jpg to a OS/2 BMP file:

                                alchemy test.jpg -O




























                   Copyright (c) 1990-1994 Handmade Software, Inc.           81 

       PCPAINT/Pictor Page Format                                          -A


                             The Pictor format was designed by John Bridges.
                             It is optimized so that an image can be loaded
                             into various IBM PC graphics adapters very
                             quickly; it does this by almost exactly
                             duplicating the organization of the graphics
                             adapter memory.  This makes the format hardware
                             dependent.

       Syntax                -A type

       Parameter           type:
                                0:320x200x4 CGA*
                                1:320x200x16 PCjr/Tandy*
                                2:640x200x2 CGA*
                                3:640x200x16 EGA
                                4:640x350x2 EGA
                                5:640x350x4 EGA
                                6:640x350x16 EGA
                                7:720x348x2 Hercules*
                                8:640x350x16 VGA
                                9:320x200x16 EGA
                                10:640x400x2 AT&T/Toshiba*
                                11:320x200x256 VGA/MCGA
                                12:640x480x16 VGA
                                13:720x348x16 Hercules InColor*
                                14:640x480x2 VGA/MCGA
                                15:800x600x2 EGA/VGA
                                16:800x600x16 EGA/VGA
                                17:640x400x256 SVGA
                                18:640x480x256 SVGA
                                19:800x600x256 SVGA
                                20:1024x768x2 SVGA
                                21:1024x768x16 SVGA
                                22:360x480x256 VGA
                                23:1024x768x256 SVGA
                           The default is 640x480x256 SVGA.
                           *These modes are not yet supported (if you are
                           interested in support for any of these modes
                           please contact us).

       Extension             .pic
                             .clp

       Creator               John Bridges

       Used by               PCPAINT
                             GRASP

       Variations            There are variations for most IBM and third party
                             graphics adapter display modes.



       82          Copyright (c) 1990-1994 Handmade Software, Inc. 

       Limitations           Only the EGA and VGA modes are supported at this
                             time.

                             Text modes are not supported.

       Comments              Some Pictor files do not contain palettes.  For
                             those files Alchemy will default to using a
                             standard palette appropriate to the display mode
                             the file was saved in.  However, the image may not
                             use the default palette; in that case you can read
                             the palette from another file with the -F false
                             colour option.

       Related options       -F   False colour

       Example               Convert the file image.pcx to a Pictor file called
                             image.pic, for 800x600x256 SVGA mode:

                                alchemy image.pcx -A19





































                   Copyright (c) 1990-1994 Handmade Software, Inc.           83 

       PCX                                                                 -p


                             PCX files are used extensively by IBM PC
                             computers.  Originally created by ZSoft for use by
                             their paint software, PCX files can be read and
                             written by almost all MS-DOS paint software and
                             desktop publishing software.

                             A variation of PCX file, DCX, is used by many MS-
                             DOS fax boards.

       Syntax                -p type

       Parameter             type:
                                  0:Standard PCX
                                  1:DCX
                                  2:PCJ
                             The default is standard PCX.

       Extension             .pcx.dcx

       Creator               ZSoft Corporation

       Used by               PC Paint
                             Publisher's Paintbrush
                             Most paint and desktop publishing software can
                             read and write PCX files.
                             Fax board software uses the DCX variation of PCX.

       Variations            1, 4, 8, and 24 bits per pixel for standard PCX
                             files.
                             1 bit per pixel for DCX files.
                             8 bits per pixel for PCJ files.

       Limitations           PCX format files are often written out
                             incorrectly; Alchemy attempts to figure out what
                             is wrong and make intelligent decisions (things
                             Alchemy can deal with include PCX files without
                             palettes, files missing the last line of image
                             data, and files with illegal (and incorrect)
                             combinations of bits per pixel and planes).


                             The 24 bit PCX file variation is new and many
                             programs which support PCX do not support the 24
                             bit variation.  Therefore, unless you are sure
                             that the software you are using can read a 24 bit
                             PCX file, you probably want to use the -8 option
                             to force Alchemy to write a paletted file when
                             generating a PCX file.





       84          Copyright (c) 1990-1994 Handmade Software, Inc. 

                             DCX files are multiple page PCX images which are
                             used by various manufacturers of fax boards and
                             fax software.  Alchemy only reads the first page
                             of a DCX file.  Alchemy always writes single page
                             DCX files.

       Comments              Because so many software packages can read and
                             write PCX files we are especially interested in
                             supporting as many variations as possible.  If you
                             have any PCX files which Alchemy does not read
                             correctly please contact us.


                             Since DCX files are always 1 bit, black and white
                             images, Alchemy assumes the use of -b -c2 -8 when
                             writing the DCX variation of PCX.


                             Recently some of the header information in PCX
                             files has been changed to include image resolution
                             information.  Some fax board software makes use of
                             this information when transmitting PCX or DCX
                             files as faxes.  See the example section below for
                             an example of how to specify image resolution when
                             writing a PCX file.


                             PCJ files are a variation of 256 colour PCX files
                             which have the palette in a separate file.  The
                             palette file has the extension .p13.  Alchemy will
                             automatically look for the palette file in the
                             same directory as the PCJ file when reading.

       Related options       -D   Specify image resolution.

       Examples              Convert the GIF file, lush.gif, to a PCX file:

                                alchemy lush.gif -p

                             Convert the scanned image, page1.tif, to a DCX
                             file:

                                alchemy page1.tif -p1

                             Convert the scanned image, page2.tif, to a DCX
                             file, specifying an image resolution of 200x100 (a
                             common resolution for fax images):

                                alchemy page2.tif -p1 -D 200 100

                             Convert the image, flower.tif, to a PCJ file:

                                alchemy flower.tif -p2



                   Copyright (c) 1990-1994 Handmade Software, Inc.           85 

       PDS                                                                --p


                             PDS labeled images are used by NASA for planetary
                             images.

       Syntax                --p

       Extensions            .ibg
                             .imq

       Creator               NASA

       Used by               NASA distributes collections of planetary images
                             on CD-ROM in PDS format.

       Variations            Reads 1 and 8 bit uncompressed and 8 bit first
                             difference Huffman compressed files.


                             Writes 8 bit gray-scale uncompressed PDS files.

       Limitations           PDS images must begin with either an "SFDU_LABEL"
                             or a "FILE_TYPE" record for Alchemy to be able to
                             identify it.


                             Occasionally a PDS labeled image has a palette.
                             There doesn't seem to be any standard format for
                             the palette; Image Alchemy handles the palettes
                             we've encountered.


                             Any portions of the PDS labels not required to
                             extract the image, such as longitude and latitude,
                             are ignored.

       Comments              Since Image Alchemy only writes gray-scale PDS
                             images, Alchemy assumes the use of the -b option
                             when writing PDS files.


                             Some PDS images actually consist of two files, a
                             label file and a data file.  To read that type
                             image you should use the name of the label file
                             and Alchemy will find the data file.

       Example               Convert the GOES file, phoenix.goe, into a PDS
                             labeled image:

                                alchemy phoenix.goe --p





       86          Copyright (c) 1990-1994 Handmade Software, Inc. 

       Portable BitMap (PBM)                                               -k


                             The Portable BitMap format was developed by Jef
                             Poskanzer to allow the transferring of black and
                             white image files between different workstations.
                             The PBM format has grown to include black and
                             white, gray-scale, and true colour images, a large
                             set of programs to convert various other image
                             formats to and from PBM, and a set of image
                             manipulation tools.

       Syntax                -k

       Extensions            .pnm
                             .pbm
                             .pgm
                             .ppm

       Creator               Jef Poskanzer

       Used by               Portable BitMap Package
                             Various workstation graphic programs

       Variations            Reads and writes 1, 8, and 24 bit RAWBITS (binary)
                             images.

                             To write out a PBM file use -b -c2.
                             To write out a PGM file use -b -c256.
                             To write out a PPM file use -24.

       Limitations           When writing a PBM file Alchemy always uses the
                             .pnm extension (the extension should be changed
                             based on the type of file being written).

       Comments              By convention the extension of a PBM file changes
                             depending on the type of image data which it is
                             storing, based on the following table:
                                  .pnm    Portable aNyMap (Any of those below)
                                  .pbm    Portable BitMap (Black and white)
                                  .pgm    Portable GrayMap (Gray-scale)
                                  .ppm    Portable PixelMap (True colour)
                             Alchemy does not make use of this convention when
                             writing images, always writing files with the
                             extension .pnm.

                             The PBM package is a set of image manipulation
                             tools which run on various workstations.  The
                             software is available free of charge via anonymous
                             ftp from expo.lcs.mit.edu as
                             contrib/pbmplus.tar.Z, ftp.ee.lbl.gov as
                             pbmplus.tar.Z, or via floppy disk from us.




                   Copyright (c) 1990-1994 Handmade Software, Inc.           87 

       Examples              Convert the file sun.im32 to a PBM file:

                                alchemy sun.im32 -k -b -c2

                             Convert the file sun.im32 to a PGM file,
                             overwriting any existing sun.pnm file:

                                alchemy sun.im32 -k -b -c256 -o

                             Convert the file sun.im32 to a PPM file called
                             image77:

                                alchemy sun.im32 image77 -k -24 -.











































       88          Copyright (c) 1990-1994 Handmade Software, Inc. 

       Puzzle                                                             --U


                             The Puzzle format is used by the UNIX supplied
                             Puzzle program

       Syntax                --U

       Extensions            .pzl
                             .puzzle
                             .cm

       Creator               Unknown

       Used by               The puzzle program.

       Variations            8 bits per pixel

       Comments              Since puzzle files are always paletted, Alchemy
                             assumes the use of the -8 option when writing a
                             puzzle file.

       Example               Convert the file einstein.im8 to a Puzzle file:

                                alchemy einstein.im8 --U































                   Copyright (c) 1990-1994 Handmade Software, Inc.           89 

       Q0                                                                 --q


                             The Q0 format is apparently commonly used by
                             various Japanese scanning, painting, and viewing
                             software to store 24 bit images.  Handmade
                             Software has no information other than a basic
                             description of the format and some sample images;
                             if you have further information on the Q0 format
                             please contact us.

       Syntax                --q

       Extensions            .q0  For pixel data
                             .rgb For pixel data
                             .fal For image header information

       Creator               Unknown

       Used by               Various Japanese image processing software.

       Variations            24 bits per pixel

       Comments              Q0 files are actually two files, one with the
                             extension .rgb or .q0 and the other with the
                             extension .fal.  The .rgb or .q0 file contains the
                             actual image data and the .fal file contains the
                             header information.  You specify the name of the
                             .rgb or .q0 file and Alchemy automatically
                             generates the name of the .fal file.

                             When writing a Q0 file Alchemy will overwrite,
                             without warning, existing .fal files.

                             Since Q0 files are always true colour, Alchemy
                             assumes the use of the -24 option when writing a
                             Q0 file.

       Example               Convert the file dogcow.gif to a Q0 file:

                                alchemy dogcow.gif --q















       90          Copyright (c) 1990-1994 Handmade Software, Inc. 

       QDV                                                                --D


                             The QDV format is used by Giffer, a Macintosh
                             program which displays and converts image files.

       Syntax                --D

       Extension             .qdv

       Creator               Steve Blackstock

       Used by               Giffer

       Variations            QDV files are always 8 bits per pixel.

       Comments              Giffer is a great shareware (Beerware_, actually)
                             program for the Macintosh that converts between
                             various image file formats and allows viewing of
                             graphics files.

                             Since QDV files are always paletted, Alchemy
                             assumes the use of the -8 option when writing QDV
                             files.

       Example               Convert the file input.tga to a qdv file:

                                alchemy input.tga --D




























                   Copyright (c) 1990-1994 Handmade Software, Inc.           91 

       QRT Raw                                                            --T


                             QRT files are generated by the QRT Ray Tracer, a
                             public domain ray-tracer for Amiga, Macintosh, and
                             IBM PC computers.

       Syntax                --T

       Extension             .raw

       Creator               Steve Korn

       Used by               QRT Ray Tracer

       Variations            24 bits per pixel

       Comments              Since QRT files are always true colour, Alchemy
                             assumes use of the -24 option when writing a QRT
                             file.

       Example               Convert the file spheres.gif to a QRT file called
                             spheres.raw:

                                alchemy spheres.gif --T































       92          Copyright (c) 1990-1994 Handmade Software, Inc. 

       RIX                                                                 -R


                             RIX files were developed by ColoRIX to use with
                             their paint software.

       Syntax                -R

       Extension             .scx
                             .rix

       Creator               RIX Softworks, Inc.

       Used by               ColoRIX software

       Variations            Reads and writes Type 0 (8 bits per pixel) and
                             Type 4 (4 bits per pixel) images.

       Limitations           We would like to add support for Type 1 and Type 2
                             images but we haven't been able to find any
                             documentation on this variation.  If you have
                             information please contact us.

       Comments              A type 0 file will be written if there are more
                             than 16 colours in the image; otherwise a type 4
                             file will be written.

                             Since RIX files are always paletted, Alchemy
                             assumes use of the -8 option when writing a RIX
                             file.

       Example               Convert the file test.gif to a RIX file:

                                alchemy test.gif -R






















                   Copyright (c) 1990-1994 Handmade Software, Inc.           93 

       Scodl                                                              --s


                             Scodl files are used by Agfa/Matrix slide
                             recorders.

       Syntax                --s type

       Parameter             type:
                                  0:Non-scalable image (pre MVP version 4.2)
                                  1:Scalable image (MVP version 4.2 or later)
                             The default is 0 (Non-scalable).

       Extension             .scd

       Creator               Agfa Corporation / Matrix Instruments Inc.

       Used by               Agfa/Matrix slide recorders

       Variations            Writes 8 and 24 bit run-length coded (RLC) images.

       Limitations           Output only.

       Comments              Agfa/Matrix made significant changes to the Scodl
                             file format when they introduced version 4.2 of
                             the MVP and Conductor software in 1992.  Old
                             version Scodl files could not be scaled by the MVP
                             software; new version Scodl files can be scaled
                             but only work the newer version of the MVP and
                             Conductor software.


                             Scalable Scodl images have the advantages that
                             they do not have to be scaled to a specific output
                             resolution and are therefore generally smaller
                             than pre-scaled Scodl images.  They can also be
                             imaged on a film recorder with any output
                             resolution or previewed on a monitor.


                             The disadvantage of scalable Scodl images is that
                             you must be using at least Scodl MVP version 4.2
                             and the Scodl MVP software does not perform very
                             high-quality scaling.  In particular, the MVP
                             software only does pixel replication scaling when
                             increasing the size of an image (this corresponds
                             to type 'a' scaling in Alchemy) and pixel
                             averaging when reducing the size of an image
                             (corresponding to Alchemy 'b' scaling).







       94          Copyright (c) 1990-1994 Handmade Software, Inc. 

                             Note that Alchemy pays attention to the aspect
                             ratio or dots per inch information specified as
                             part of the command line or present in the
                             original image when converting to a Scodl scalable
                             image.  Therefore you should ensure that this
                             information is correct when writing a Scodl
                             scalable image.

                             When writing Non-scalable Scodl files the image
                             should be scaled up to either 2000x1366 or
                             4000x2732 to fill the slide.

                             There are some limitations with the MVP software
                             driver supplied by Agfa/Matrix:


                            24 bit Scodl files are not correctly interpreted by
                            the MVP driver version 4.1 and earlier.  8 bit
                            images are correctly interpreted.


                            When sending very large images to the background
                            MVP driver you must be using version 4.0 or later
                            and have lots of EMS memory (4 megabytes is
                            recommended).  When using the foreground MVP
                            program turning on disk caching is necessary.


       Examples              Convert the file picture.im32 to a Scodl file
                             using high quality scaling and preserving the
                             aspect ratio:

                             alchemy picture.im32 --s -Xc2000 -Yc1366 -+

                             Do the same thing, but generate a scalable Scodl
                             file:

                             alchemy picture.im32 --s1


















                   Copyright (c) 1990-1994 Handmade Software, Inc.           95 

       Silicon Graphics Image (SGI)                                        -n


                             Silicon Graphics Image files are used by Silicon
                             Graphics workstations.

       Syntax                -n compressionType

       Parameter             compressionType:
                                  0:Verbatim (uncompressed)
                                  1:RLE compressed
                             The default is 0 (Verbatim).

       Extension             .sgi

       Creator               Silicon Graphics, Inc.

       Used by               Silicon Graphics workstations.

       Variations            Reads and writes 8 (gray-scale) and 24 bit
                             verbatim (uncompressed) and RLE files.

       Comments              Only gray-scale images may be 8 bit files.
                             Alchemy will automatically switch to 24 bit mode
                             when writing a colour image.

       Examples              Convert the Sun raster file sun.im8 to a SGI file
                             called sgiout:

                                alchemy sun.im8 sgiout -n -.

                             Do the same thing, but write out a RLE compressed
                             SGI file:

                                alchemy sun.im8 sgiout -n1 -.





















       96          Copyright (c) 1990-1994 Handmade Software, Inc. 

       SPOT Image                                                         --S


                             SPOT Image files are high-resolution satellite
                             images produced by SPOT Image Corporation.

       Syntax                --S

       Extensions            For GIS (tape) format:
                                  .hdr    Header information
                                  .bil    Pixel data
                                  .clr    Palette data [optional]

                             For CCT (CD-ROM) format:
                                  .dat

       Creator               SPOT Image Corp.

       Used by               SPOT Image Corp.

       Variations            Reads and writes 8 bits per pixel for GIS (tape)
                             format files

                             Reads 8 and 24 bits per pixel for CCT (CD-ROM)
                             format files

       Limitations           Only GIS (tape) format images are currently
                             written; contact us if you are interested in
                             writing CCT SPOT Image files.

       Comments              SPOT Image GIS (tape) images are actually three
                             files.  You specify the name of the .hdr file and
                             Alchemy automatically generates the name of the
                             .bil and .clr files.


                             If no palette file (.clr file) exists Alchemy will
                             assume the image is grayscale.


                             There may also be a statistics file with a .stx
                             extension, but Alchemy ignores this file.


                             When writing a SPOT file Alchemy will overwrite,
                             without warning, existing .bil and .clr files.


                             When reading a CCT (CD-ROM) format image specify
                             the complete path and name of the image file.  For
                             example, on an MS-DOS system:
                             alchemy l:\scene04\imag_04.dat -g will convert the
                             scene 4 image to a GIF file.



                   Copyright (c) 1990-1994 Handmade Software, Inc.           97 

       Example               Convert the Erdas file, phoenix.lan, to a SPOT
                             Image file:

                                alchemy phoenix.lan --S




















































       98          Copyright (c) 1990-1994 Handmade Software, Inc. 

       Stork                                                               -K


                             Stork files are CMYK images used by Stork's colour
                             proofing machines.

       Syntax                -K compressionType

       Parameter             compressionType:
                                  0:None
                                  1:Run length coded
                             The default is none.

       Extensions            .idx Header information
                             .pre Image data
                             .tab Colour lookup table

       Creator               Stork Colorproofing B.V.

       Used by               Stork Colorproofing machines

       Variations            Reads and writes 32 KCMY, 32 KCMY RLC, 16 CLU, and
                             16 CLU RLC images (type 100, 101, 300, and 301,
                             respectively).

       Limitations           Alchemy can't write paletted files with more than
                             256 colours.

                             When reading paletted files with more than 256
                             colours they are treated as true colour.

       Comments              Stork images are stored in two or three files
                             (depending on whether or not there's a colour
                             lookup table associated with the image).  The
                             filename given to Alchemy should be the name of
                             the data file (normally with a suffix of .pre);
                             Alchemy will generate the names of the other files
                             by stripping the extension and appending .idx for
                             the index file and .tab for the colour lookup
                             table (if any).


                             Alchemy will overwrite existing .idx and .tab
                             files without warning when creating Stork files.

                             Since Stork images are CMYK data files you will
                             probably want to use an undercolour removal file
                             to control the RGB to CMYK conversion process; see
                             the undercolour removal file command in Chapter 8
                             for more information.

       Related options       -C   Undercolour Removal File




                   Copyright (c) 1990-1994 Handmade Software, Inc.           99 

       Example               Convert the file image.tga to an uncompressed
                             Stork image called image.pre and image.idx, using
                             the undercolour removal file sample.ucr:

                                alchemy image.tga -K -Csample.ucr



















































       100         Copyright (c) 1990-1994 Handmade Software, Inc. 

       Sun Icon                                                           --N


                             Sun Icon files are used by Sun Microsystems
                             workstations to contain icon information.

       Syntax                --N

       Extensions            .icon
                             .ico

       Creator               Sun Microsystems, Inc.

       Used by               Sun workstations

       Variations            1 bit, black and white.


       Comments              This is not the same format as Sun Raster (see
                             below).

                             Since Sun Icon files are always black and white,
                             Alchemy assumes use of the -8, -c2, and -b options
                             when writing a Sun Icon file.

       Example               Convert the sun raster file icon.im1 to a sun icon
                             file called program.ico:

                                alchemy icon.im1 program.ico --N



























                   Copyright (c) 1990-1994 Handmade Software, Inc.          101 

       Sun Raster                                                          -s


                             Sun Raster files are used by Sun Microsystems
                             workstations.

       Syntax                -s compressionType

       Parameter             compressionType:
                                  0:None
                                  1:Run length compression
                             The default is None.

       Extensions            .rast
                             .ras
                             .im
                             .im1
                             .im8
                             .im24
                             .im32

       Creator               Sun Microsystems, Inc.

       Used by               Sun workstations

       Variations            Reads 1, 8, 24, and 32 bit Standard, BGR, RGB, and
                             Byte Encoded (RLE) files.

                             Writes 1, 8, 24, and 32 bit Standard files, and 1
                             and 8 bit Byte Encoded (RLE) files.

       Limitations           For a short time a version of the PBM toolkit
                             wrote Sun Raster files which had the wrong RGB
                             order.  Unfortunately there seem to be many images
                             which were generated with this incorrect RGB
                             order.  Please be aware that Alchemy's Sun Raster
                             reading and writing capability has been
                             extensively tested and compared to various other
                             tools; the RGB order we use is correct.

       Comments              Sun Raster files are normally not compressed and
                             so take up lots of disk space.


                             There is no standard extension for Sun Raster
                             files; the extensions that Alchemy uses seem to be
                             the most common.

       Examples              Convert the SGI file sgiout to a sun raster file
                             called sun.im8:

                                alchemy sgiout sun.im8 -s




       102         Copyright (c) 1990-1994 Handmade Software, Inc. 

                             Do the same thing, but write out a compressed sun
                             raster file:

                                alchemy sgiout sun.im8 -s1




















































                   Copyright (c) 1990-1994 Handmade Software, Inc.          103 

       TIFF (Tagged Interchange File Format)                               -t


                             TIFF is designed to be a universal raster image
                             format.  It's very popular with desktop publishing
                             packages.

       Syntax                -t compressionType

       Parameter             compressionType:
                                  0:None
                                  1:LZW
                                  2:PackBits
                                  3:Group III Fax
                                  4:Group IV Fax
                                  5:CCITT RLE
                                  100:None with one strip
                                  101:LZW with one strip
                                  102:PackBits with one strip
                                  103:Group III Fax with one strip
                                  104:Group IV Fax with one strip
                                  105:CCITT RLE with one strip
                             The default is LZW Compression.

       Extensions            .tiff
                             .tif

       Creator               Aldus Corp.
                             Microsoft Corp.

       Used by               Various desktop publishing and scanning software.

       Variations            Reads TIFF class B, G, R, and most class P files.


                             Reads 1 through 8, 12, 24, and 32 bit images
                             (ignoring the alpha channel for 32 bit images).


                             Input compression types supported are raw, LZW,
                             PackBits, Group III fax, Group IV fax, CCITT RLE
                             (byte and word aligned), NeXT, Thunderscan, PICIO,
                             and SGI RLE.


                             Writes class B, G, P, and R files, depending on
                             the input file and options specified.


                             Writes 1, 4, 8, and 24 bit images.


                             Output compression types supported are raw, LZW,
                             PackBits, Group III fax, Group IV fax, and CCITT
                             RLE.

       104         Copyright (c) 1990-1994 Handmade Software, Inc. 

       Limitations           Class P TIFF files can only be read if they have
                             1, 4, or 8 bits per pixel.

       Comments              TIFF files are often written out incorrectly;
                             Alchemy attempts to figure out what is wrong and
                             make intelligent decisions.  If you have TIFF
                             files which Alchemy cannot read please contact us.

                             1,4, and 8 bit output files are paletted unless
                             the palette is all gray, in which case the output
                             is a gray-scale file.

                             When writing TIFF files using any of the fax
                             compression types (Group III, Group IV and CCITT
                             RLE), Alchemy uses a photometric interpretation of
                             minIsWhite.

                             See Appendix A, Answers to Frequently Asked
                             Questions, for more information on writing TIFF
                             files which conform to the various TIFF classes.

                             LZW compression is patented by Unisys Corporation
                             and used under license (for more information see
                             Appendix I, Acknowledgments).

       Example               Convert the file input.gif to an uncompressed
                             gray-scale TIFF file called output.tif:

                                alchemy input.gif output.tif -t0 -b



























                   Copyright (c) 1990-1994 Handmade Software, Inc.          105 

       Targa                                                               -a


                             Targa files were created to support the line of
                             Targa graphics cards.  The Targa format is popular
                             with scanners and high end paint packages.

       Syntax                -a outputType

       Parameter             outputType:
                                  0:Uncompressed
                                  1:Run Length Coded
                                  10:Uncompressed, no footer
                                  11:Run Length Coded, no footer
                             The default is 0 (Uncompressed).

       Extension             .tga

       Creator               Truevision, Inc.

       Used by               Various scanning and paint software.

       Variations            Reads 8, 15, 16, 24, and 32 bit images, ignoring
                             the alpha channel for 32 bit images.

                             Writes 8, 15, 16, 24, and 32 bit images, writing
                             an empty alpha channel for 32 bit images.

       Comments              15 and 16 bit output are actually the same except
                             for one field in the header.

                             Targa files allow a footer containing additional
                             information such as aspect ratio.  However some
                             software is unable to read Targa files which have
                             a footer, so Alchemy allows all valid combinations
                             to be written.  The most common variant for
                             software to be able to read is 24 bit uncompressed
                             (specify -a0 and -24).

       Examples              Convert the file input.tif to an uncompressed 24
                             bit Targa file:

                                alchemy input.tif -a -24

                             Convert the file input.tif to an uncompressed 15
                             bit Targa file called output.tga with no footer:

                                alchemy input.tif output.tga -a10 -15








       106         Copyright (c) 1990-1994 Handmade Software, Inc. 

       Utah Raster Toolkit (RLE)                                          --u


                             The Utah Raster Toolkit is a set of public domain
                             utilities for manipulating and converting images
                             for various workstations.

       Syntax                --u

       Extension             .rle

       Creator               The University of Utah
                             The University of Michigan

       Used by               Utah RLE toolkit

       Variations            Reads and writes 1 and 3 channel 8 bits per pixel
                             files; the Alpha Channel is ignored during
                             reading.

       Limitations           While reading, files which are 1 channel and have
                             either no colour map or a single channel colour
                             map are assumed to be gray-scale images.  The
                             colour map, if present, will be used as a gamma
                             correction table.

                             Files which are 1 channel and have a 3 channel
                             colour map are assumed to be paletted colour
                             files.

                             Files which are 3 channel are assumed to be true
                             colour.

                             When writing RLE files Alchemy will generate a 1
                             channel file with a 3 channel colour map for
                             paletted images and a 3 channel file with no
                             colour map for true colour images.

       Comments              The Utah Raster Toolkit is available free of
                             charge via
                             anonymous ftp as pub/urt-3.0.tar.Z from
                             cs.utah.edu, weedeater.math.yale.edu, or
                             freebie.engin.umich.edu or via floppy disk from
                             us.

       Example               Convert the PBM file, image.ppm, to a Utah RLE
                             file:

                                alchemy image.ppm --u







                   Copyright (c) 1990-1994 Handmade Software, Inc.          107 

       VITec                                                               -T


                             VITec files are used by VITec image processing
                             software.

       Syntax                -T

       Extension             .vit

       Creator               VITec

       Used by               VITec ELT

       Variations            Reads 8 bit grayscale and 24 bit colour files,
                             untiled and tiled files.

                             Writes 8 bit grayscale and 24 bit colour files
                             untiled files.

       Example               Convert the file map.erm to a VITec file:

                                alchemy map.erm -T

































       108         Copyright (c) 1990-1994 Handmade Software, Inc. 

       Vivid                                                              --I


                             Vivid is a shareware ray-tracer for MS-DOS
                             computers.

       Syntax                --I (upper case i)

       Extension             .img

       Creator               Steven B. Coy

       Used by               Vivid Ray Tracer

       Variations            Reads and writes 24 bit RLE files.

       Comments              The Vivid Ray Tracer is a shareware program for
                             PCs and is available from:
                                  Stephen Coy
                                  15205 NE 13th Pl., #2904
                                  Bellevue, WA  98007
                             or from us.

       Example               Convert the file spheres.qrt to a Vivid file:

                                alchemy spheres.qrt --I






























                   Copyright (c) 1990-1994 Handmade Software, Inc.          109 

       Windows Bitmap (BMP)                                                -w


                             Windows BMP files are used by Microsoft Windows.

       Syntax                -w compressionType

       Parameter             compressionType:
                                  0:None
                                  1:RLE
                                  10:Write an ICOn file
                             The default is none.

       Extension             .bmp

       Creator               Microsoft Corp.

       Used by               Microsoft Windows

       Variations            Reads 1, 4, 8, and 24 bit RGB (raw), RLE4, and
                             RLE8 files.

                             Writes 1, 4, 8, and 24 bit RGB (raw), RLE4, and
                             RLE8 files.

       Limitations           Several of the programs which claim to read and
                             write RLE files do not do so correctly; we do not
                             recommend writing RLE files unless you have
                             verified that they work with your intended
                             application.

       Comments              Microsoft supplied Windows utilities cannot read
                             nor write RLE4 or RLE8 files.


                             If you are converting an image to use as wallpaper
                             on a 16 colour display you will want to match the
                             palette of the output image to one of the existing
                             16 colour BMP images supplied with Windows
                             (chess.bmp, for example).  If you do not do this
                             the wallpaper will not be loaded correctly.  See
                             the example section below.


                             If you are converting an image to use as wallpaper
                             on a 256 colour Windows 3.1 display you will want
                             to reserve the first 8 colours.  Use the -c 256 8
                             option to do this (see below for an example).
                             This will force the first 8 colours of the palette
                             to be the standard Windows colours.






       110         Copyright (c) 1990-1994 Handmade Software, Inc. 

                             If you are writing a Windows icon (.ico) file you
                             must scale the image to a width and a height of
                             16, 32, or 64 pixels (32 being the best choice,
                             since Windows displays all icons as 32x32).  Also,
                             Windows seems to remap all icons to the standard
                             16 colours, so the best results can be obtained if
                             you match the palette of your icons to an existing
                             icon (see the -f option).  If you don't have any
                             other icons you can also match to one of the 16
                             colour wallpaper files supplied with Windows.


                             Alchemy can write a BMP file which contains an
                             identity palette as specified in the Microsoft
                             Multimedia Development Kit.  These images provide
                             for quicker bitmap loading when used with the
                             Multimedia Extensions.  A palette identity file
                             has the first and last 10 palette entries reserved
                             for 20 system defined colours.  Alchemy will write
                             such an image if you specify -c 246 10 as part of
                             the command line.  Note that ordinarily this would
                             produce a file which has 246 palette entries, but
                             in this special case the file will have 256
                             palette entries (20 fixed by the Windows
                             specifications and 236 chosen by Alchemy).  Note
                             that you can also specify a number smaller than
                             246, but the palette will always have 256 colours
                             (since the last 10 have to occupy positions 246
                             through 255).

       Related options       -c   Specify number of colours
                             -f   Match to existing palette

       Examples              Convert the image test.gif to a Windows BMP file:

                                alchemy test.gif -w

                             Convert the image test.gif to a 16 colour Windows
                             BMP file to be used as wallpaper (the file
                             chess.bmp is supplied with Windows 3.0 (substitute
                             leaves.bmp when using Windows 3.1); this example
                             assumes that it is in the current directory):

                                alchemy test.gif -f chess.bmp -w

                             Convert the image test.gif to a 256 colour Windows
                             BMP file to be used as wallpaper with Windows 3.1:

                                alchemy test.gif -c256 8 -w

                             Convert the image test.gif to an icon file for use
                             with Windows 3.1:

                                alchemy test.gif -Xb32 -Yb32 -w 10
                                     -f leaves.bmp

                   Copyright (c) 1990-1994 Handmade Software, Inc.          111 

                             Convert the image test.gif to an identity palette
                             BMP file:

                                alchemy test.gif -w -c 246 10




















































       112         Copyright (c) 1990-1994 Handmade Software, Inc. 

       WordPerfect Graphic File                                            -W


                             WordPerfect files are images which can be imported
                             into WordPerfect and various other word processors
                             and desktop publishing programs.

       Syntax                -W

       Extension             .wpg

       Creator               WordPerfect Corp.

       Used by               WordPerfect

       Variations            1 through 8 bits per pixel are supported.

       Comments              In addition to raster images WordPerfect files may
                             contain vectors and text information.  Such
                             information is lost when reading WordPerfect
                             files.

                             Since WordPerfect Graphic files are always
                             paletted, Alchemy assumes use of the -8 option
                             when writing a WordPerfect Graphic file.

       Example               Convert the image, newpict.pcx, to a black and
                             white WPG file:

                                alchemy newpict.pcx -b -c2 -W


























                   Copyright (c) 1990-1994 Handmade Software, Inc.          113 

       XBM                                                                --b


                             XBM files are used by the X Windowing System.  XBM
                             files are C source code files which can be read
                             and written by various X utilities and are
                             designed to be included in C source code for use
                             as icons and other bit-mapped graphic images.

       Syntax                --b

       Extensions            .xbm
                             .bm

       Creator               MIT

       Used by               The X Windowing system

       Variations            1 bit per pixel

       Limitations           Because .xbm files are actually C source code
                             files there can be many variations of .xbm files.
                             Since adding a C preprocessor to Alchemy to handle
                             all the theoretically allowable .xbm files is
                             impractical we have instead designed Alchemy to
                             interchange .xbm files with the PBM utilities and
                             the X supplied utilities, and to read the sample
                             .xbm files from Sun Microsystems.  If you run
                             across any .xbm files which Alchemy cannot read
                             please contact us.

                             The hotspot field is ignored when reading .xbm
                             files.

                             Since XBM files are always black and white,
                             Alchemy assumes use of the -8, -c2, and -b option
                             when writing a XBM file.

       Comments              Most of the X supplied utilities (bitmap, for
                             example) are designed to edit small .xbm images.

       Example               Convert the file picture.im32 to an XBM file using
                             high quality scaling and preserving the aspect
                             ratio:

                             alchemy picture.im32 --b -Xb64 -+










       114         Copyright (c) 1990-1994 Handmade Software, Inc. 

       XPM                                                                --x


                             XPM files are used by the X Windowing System.  XPM
                             files are C source code files which can be read
                             and written by various X utilities and are
                             designed to be included in C source code for use
                             as icons and other bit-mapped graphic images.

       Syntax                --x type

       Parameter             type:
                                  0:XBM similar style
                                  1:XPM3 style
                                  2:XPM2 style

                                  10:XBM similar style with 48 bit colours
                                  11:XPM3 style with 48 bit colours
                                  12:XPM2 style with 48 bit colours
                             The default is XBM similar style (see the Comments
                             section below for a discussion of the different
                             XPM file types).

       Extensions            .xpm
                             .pm

       Creator               MIT

       Used by               The X Windowing system

       Variations            8 bits per pixel

       Limitations           Because .xpm files are actually C source code
                             files there can be many variations of .xpm files.
                             Since adding a C preprocessor to Alchemy to handle
                             all the theoretically allowable .xpm files is
                             impractical we have instead designed Alchemy to
                             interchange .xpm files with the PBM utilities and
                             the X supplied utilities, and to read the sample
                             .xpm files from IBM.  If you run across any .xpm
                             files which Alchemy cannot read please contact us.


                             Some XPM files contain colour names instead of
                             colour values for some of the colours.  The
                             conversion information to convert these names into
                             values is in a file supplied with the X Windowing
                             system called rgb.txt.  When needed, Alchemy will
                             look for this table in the following directories:
                             the current directory, /usr/lib/X11, $OPENWINHOME,
                             and /usr/openwin/lib.  If your system has the
                             rgb.txt file in a different location you may have
                             to copy it to the current directory (its location
                             is system dependent; ask you system administrator
                             if you need help finding it).

                   Copyright (c) 1990-1994 Handmade Software, Inc.          115 

       Comments              The different type XPM files can be identified as
                             follows:

                             Type 0 (XBM similar style):
                                #define type0_format 1
                                ...
                                static char *type0_colors[] = {
                                "a", "#000000",
                                "b", "#ff0000",
                                ...

                             Type 1 (XPM3 style):
                                /* XPM */
                                static char * type1[] = {
                                "32 20 12 1",
                                "a c #000000",
                                "b c #ff0000",
                                ...

                             Type 2 (XPM2 style):
                                ! XPM2
                                32 20 12 1
                                a c #000000
                                b c #ff0000
                                ...


                             The 48 bit colour XPM files are indentical except
                             that the colour values are written as a 48 bit
                             number (instead of a 24 bit number).  Some
                             software expects XPM files that have 48 bit
                             numbers (Alchemy automatically reads either).  For
                             example:

                             Type 10 (XBM similar style with 48 bit colours):
                                #define type0_format 1
                                ...
                                static char *type0_colors[] = {
                                "a", "#000000000000",
                                "b", "#ffff00000000",
                                ...

                             The other formats (11 and 12) are analogous.

                             When writing an XPM file with less than 27 colours
                             Alchemy writes 1 character XPM files, otherwise
                             Alchemy writes 2 character XPM files.


                             XPM files are usually quite small, therefore many
                             utilities (the PBM toolkit for example) may have
                             trouble reading large XPM files.




       116         Copyright (c) 1990-1994 Handmade Software, Inc. 

                             Since XPM files are always paletted, Alchemy
                             assumes use of the -8 option when writing a XPM
                             file.

       Example               Convert the file picture.im32 to an XPM file using
                             high quality scaling and preserving the aspect
                             ratio:

                                alchemy picture.im32 --x -Xb64 -+















































                   Copyright (c) 1990-1994 Handmade Software, Inc.          117 

       XWD                                                                --w


                             XWD is the file format used by xwd, the X window
                             dumping utility.

       Syntax                --w type

       Parameter             type:
                                  0:Z type
                                  1:XY type
                             The default is Z type.

       Extension             .xwd

       Creator               MIT

       Used by               The X Windowing System

       Variations            Reads 1, 4, 8, and 24 bits per pixel Z format and
                             1, 4, and 8 bit XY format XWD files.

                             Writes 1, 8, and 24 bits per pixel Z format and 1
                             and 8 bit XY format XWD files.

       Example               Convert the XBM file, icon.xbm, to an XWD file:

                                alchemy icon.xbm --w




























       118         Copyright (c) 1990-1994 Handmade Software, Inc. 

                                                                              5



       General Options
       ------------------------------------------------------------------------


       Introduction          General options are options which do not affect
                             the conversion of the image.  They control such
                             things as the overwriting of existing files and
                             the way that memory is used.












































                   Copyright (c) 1990-1994 Handmade Software, Inc.          119 

       Conserve Memory                                                     -$


       Purpose               Use as little memory as possible when converting
                             images.

       Syntax                -$ (dollar sign)

       Comments              Normally Alchemy tries to work on chunks of the
                             image several lines long to improve performance.
                             Use of the -$ option will cause it to use the
                             smallest size chunks possible for the conversion
                             being performed.  On MS-DOS based systems using
                             the standard version of Alchemy this will usually
                             allow conversion of larger images than would
                             otherwise be possible.  On UNIX systems and in the
                             386 Enhanced version of Alchemy this may reduce
                             paging when converting very large images.

       Example               Convert the image giant.tga to a TIFF file
                             conserving memory:

                                alchemy giant.tga -$ -t

































       120         Copyright (c) 1990-1994 Handmade Software, Inc. 

       Display Image Stats                                                 -x


       Purpose               Display image statistics.

       Syntax                -x

       Comments              Displays image type, size, number of colours,
                             aspect ratio, resolution, and compression ratio.

       Example               Find out about the image called image.tga:

                                alchemy -x image.tga











































                   Copyright (c) 1990-1994 Handmade Software, Inc.          121 

       Do Not Alter Output Filename                                        -.


       Purpose               Disable automatic appending of the output image
                             type to the output file name.

       Syntax                -. (period)

       Comments              By default, if there's no '.' in the output
                             filename, Alchemy will add an extension indicating
                             the type of file.  If the -. option is specified
                             no extension will be added.

                             This is most useful on non-MS-DOS systems where
                             '.' is not a special character in filenames.

       Example               Convert the file called infile.gif to a PCX file
                             called outfile (if you did not use the -. option
                             Alchemy would automatically change the output file
                             name to outfile.pcx):

                                alchemy infile.gif outfile -p -.


































       122         Copyright (c) 1990-1994 Handmade Software, Inc. 

       Help                                                                -h


       Purpose               Give you information on how to use Image Alchemy.

       Syntax                -h option

       Parameter             option:
                                  0:General help
                                  1:General options
                                  2:Output formats A through L
                                  3:Output formats M through Z
                                  4:Colour options
                                  5:Scaling options
                                  6:Display options (MS-DOS Only)
                                  7:PostScript input options
                             Default is 0, general help

       Limitations           The help option cannot be combined with any other
                             options.

       Comments              The help information given by this command is only
                             a summary.

                             The numbers in braces after the command name refer
                             to the page numbers in this manual.

       Related options       -?   support and update information

       Example               Get help on the colour options:

                                alchemy -h4
























                   Copyright (c) 1990-1994 Handmade Software, Inc.          123 

       Override Input Type                                                 -=


       Purpose               Force Alchemy to treat the input file as the
                             specified file type.  This can be used if Alchemy
                             cannot identify or misidentifies the format of an
                             input image.

       Syntax                -= inputType

       Parameter             The inputType must be a valid number identifying a
                             supported format.  The inputTypes are as follows:


                                ADEX..............24     Macintosh PICT....10
                                Alpha BMP.........42     MacPaint..........49
                                Autologic.........28     MTV...............17
                                AVHRR.............43     OS/2 BitMaP.......55
                                Binary (BIF)......31     PCPaint/Pictor....29
                                Calcomp...........50     PCX................9
                                CALS..............41     PDS...............37
                                Core IDC..........66     Portable BitMap...13
                                Cubicomp PM.......44     Puzzle............51
                                Dr. Halo CUT......45     Q0................21
                                ER Mapper Raster..59     QDV...............18
                                Erdas Image.......19     QRT Raw...........20
                                First Publisher...46     RIX...............38
                                Gem VDI Image.....22     SGI Image.........11
                                GIF................1     Spot Image........39
                                GOES..............40     Stork.............32
                                Hitachi Raster....63     Sun Icon..........52
                                HP PCL............15     Sun Raster.........8
                                HP-48sx GROB......60     Targa..............6
                                HSI JPEG..........30     TIFF...............4
                                HSI Palette........3     Utah RLE..........23
                                HSI Raw............5     VITec.............64
                                IBM Picture Maker.48     Vivid IMG.........16
                                IFF/ILBM...........7     Windows BitMaP....12
                                Img Software Set..61     WP................27
                                Jovian VI.........36     X BitMap (XBM)....35
                                JPEG...............2     X PixMap (XPM)....47
                                Lumena CEL........62     XWD...............33


       Comments              Rarely will Alchemy misidentify a file; the file
                             is usually damaged in some way when this happens.
                             If the file is damaged, or if you specify an input
                             type that does not correspond to the actual type
                             of the image, the results will be unpredictable.

       Example               Convert the file unknown.xxx to an OS/2 Bitmap
                             file called output.bmp, forcing unknown.xxx to be
                             treated as a Sun Raster image:

                                alchemy unknown.xxx output.bmp -O -=8

       124         Copyright (c) 1990-1994 Handmade Software, Inc. 

       Overwrite                                                           -o


       Purpose               Allow Alchemy to overwrite existing files on the
                             disk.

       Syntax                -o

       Comments              Image Alchemy will not overwrite an existing file
                             unless the -o option is specified.

       Limitations           The input file name and the output file name
                             cannot be the same.

       Example               Convert the file input.tga to a GIF file called
                             output.gif, overwriting the existing file called
                             output.gif:

                                alchemy input.tga output.gif -g -o





































                   Copyright (c) 1990-1994 Handmade Software, Inc.          125 

       Program information                                                 -?


       Purpose               Give you information on how to get support for
                             Image Alchemy or inquire about update information.

       Syntax                -?

       Comments              UNIX users have to escape the question mark with a
                             back-slash (instead of -? use -\?).  This is
                             because the UNIX shell will attempt to perform
                             wildcard expansion on the question mark.

       Limitations           The information option cannot be combined with any
                             other options.

       Related options       -h   help with commands

       Example               Get support information:

                                alchemy -?



































       126         Copyright (c) 1990-1994 Handmade Software, Inc. 

       Quiet                                                               -Q


       Purpose               Suppress all status messages (but not error
                             messages).

       Syntax                -Q

       Comments              This is useful when running Alchemy in the
                             background on UNIX systems or in batch files on
                             MS-DOS systems (and you don't want the output of
                             Alchemy scrolling important messages off of the
                             screen).

       Limitations           There is no way to suppress error messages.

       Example               Convert the file dummy.gif to a PCX file but don't
                             report any status messages:

                                alchemy dummy.gif -Q -p




































                   Copyright (c) 1990-1994 Handmade Software, Inc.          127 

       Warnings                                                           --W


       Purpose               Treat missing input files, unidentifiable input
                             files, and non-overwriteable output files as a
                             non-fatal errors.

       Syntax                --W

       Comments              When used in conjunction with the Wildcard option
                             (see below) the Warnings option allows Alchemy to
                             proceed even when certain error conditions occur.
                             Specifically, any input files which are missing or
                             can't be identified as valid image files and any
                             output files which already exist but are not to be
                             overwritten are skipped and processing continues
                             with the next file.

                             At the end of processing Alchemy displays lists of
                             the files which were not found, which could not be
                             identified, and which already existed but could
                             not be overwritten.

                             This option was added at the request of our
                             customers who routinely convert large numbers of
                             files and don't want Alchemy to stop if it finds a
                             file missing or finds that an output file already
                             exists.

       Limitations           Any errors which occur during the processing of an
                             image file are always fatal.

                             This option can only be used with the Wildcard
                             option.

       Examples              Convert all the GIF files in the current directory
                             to JPEG files, skipping any files which can't be
                             identified or already have existing JPEG files:

                                alchemy -- *.gif -j --W
















       128         Copyright (c) 1990-1994 Handmade Software, Inc. 

       Wildcard                                                            --


       Purpose               Allow the conversion of multiple files with a
                             single execution of Alchemy.

       Syntax                -- (dash)

       Comments              The wildcard option allows you to specify multiple
                             file names and file names which include wild card
                             characters.  Alchemy will perform the same
                             conversion for each input file name that it finds.


                             On MS-DOS systems the use of the wildcard option
                             (--) is not required if the first file name
                             specified includes a wildcard character (* or ?);
                             however to reduce confusion it is still
                             recommended.

       Limitations           The wildcard option (--) must be specified before
                             any file names.


                             If you are using the wildcard option you may not
                             specify an output file name;  the file names are
                             automatically generated by substituting an
                             appropriate extension to the input file names.  If
                             you do specify an output file name it will be
                             misinterpreted as another input file.  An output
                             path name may specified and all output files will
                             be stored there (see the Examples section below
                             for an example of this).


                             Any error will terminate the execution of Alchemy;
                             any images which appear in the filename list after
                             the one causing the error will not be processed.
                             This includes attempting to overwrite an already
                             existing file without specifying the -o option.
                             If you use the --W option in conjunction with
                             wildcards certain errors will be treated as
                             warnings and not cause Alchemy to terminate.
                             These errors are:  missing input files, input
                             files which could not be identified, and output
                             files which already existed but could not be
                             overwritten (because the -o option was not
                             specified).








                   Copyright (c) 1990-1994 Handmade Software, Inc.          129 

                             Alchemy does not intelligently retain information
                             between files.  For example, if you are matching a
                             group of files to an existing palette, the inverse
                             palette generation step only needs to be performed
                             once, but it is in fact done for each file.  This
                             only affects the speed of conversions, not the
                             quality.

       Examples              Convert all the GIF files in the current directory
                             to JPEG files:

                                alchemy -- *.gif -j

                             Convert all the TIFF files in the directory \tiff
                             to PCX files in the directory \images\output:

                                alchemy -- \tiff\*.tif -p \images\output

                             Convert all the GIF files in the current
                             directory, in the directory \images, and in the
                             directory \more to GIF files, scaling them to be
                             no larger than 640x480 and write them to the
                             directory \small:

                                alchemy -- *.gif \images\*.gif \more\*.gif   -g
                                -Xb640 -Yb480 -+ \small

                             Convert the files madonna.gif, bay4.gif,
                             everest.tga, and basil.tif to JPEG files,
                             overwriting any existing files:

                                alchemy -- madonna.gif bay4.gif    everest.tga
                                basil.tif -o -j

                             Convert the files test1.tif, test2.tif, and
                             new*.gif to ILBM files, matching them to the
                             palette from the file output.pal:

                                alchemy -- test1.tif test2.tif new*.gif -f   ou
                                tput.pal -i
















       130         Copyright (c) 1990-1994 Handmade Software, Inc. 

                                                                              6



       Colour and Palette Options
       ------------------------------------------------------------------------


       Introduction          Colour and Palette options are options which
                             affect the appearance of the output image.  They
                             control such things as the number of colours in
                             the output image and the dithering techniques
                             used.











































                   Copyright (c) 1990-1994 Handmade Software, Inc.          131 

       Black and White                                                     -b


       Purpose               Convert the image to black and white or gray-
                             scale.

       Syntax                -b

       Comments              The -b option causes an image to be converted to
                             either black and white or gray-scale, depending on
                             the use of the -c option.  If -c2 is specified the
                             output image will be black and white.  Any other
                             number of colours specified with -c will cause
                             Alchemy to generate a gray scale file with that
                             many shades of gray in the output image.  If the -
                             c option is not used the default is to write a
                             file with 256 shades of gray when converting from
                             a true colour image.  When converting from a
                             paletted image the number of shades of gray
                             defaults to the number of colours in the original
                             image.

                             The shades of gray are uniformly distributed from
                             0 to 255.

                             When converting from true colour the image will be
                             changed to a paletted image unless the -24 option
                             is used.

       Related options       -8   Paletted output
                             -24  True colour output
                             -c   Specify number of colours

       Examples              Convert the file sample.jpg into a 256 shades of
                             gray raw file:

                                alchemy sample.jpg -b -r

                             Convert the file madonna.jpg into a 4 shades of
                             gray gif file called gray.gif:

                                alchemy madonna.gif gray.gif -b -c4 -g














       132         Copyright (c) 1990-1994 Handmade Software, Inc. 

       Colours                                                             -c


       Purpose               Specify the number of colours for the output file.

       Syntax                -c colours [reserveColours]

       Parameters            colours:
                                  Specifies the number of colours in the output
                             image.  May be between 2 and 256.

                             reserveColours:
                                  Specifies the number of colours to reserve in
                             the output image.  May be between 0 and 255.

       Comments              If the input file has a larger number of colours
                             than specified for the output file, the image will
                             be quantized using Heckbert's median cut algorithm
                             and dithered.  For further information on
                             Heckbert's median cut algorithm see Appendix B,
                             Colour and Dithering.

                             The number of colours to reserve is an optional
                             parameter.  If it is present it causes the
                             specified number of colours to be reserved from
                             the beginning of the palette.  The output image
                             will not contain any of those colour indices.
                             This can be useful if you have menus or other
                             information you wish to display at the same time
                             as the images and they use colours at the
                             beginning of the palette.  The menu colours will
                             then not interfere with the image.  The first
                             indices are set to black unless 16 is specified,
                             in which case they are set to the standard VGA
                             colour palette.

       Limitations           Specifying the number of colours only has an
                             effect if you are writing a paletted file (using
                             the -8 option) or if the output file type is
                             always paletted.

                             Converting an image with a large number of colours
                             to a small number of colours (less than 8) will
                             usually give poor results.

                             The reserved colours will be set to black unless
                             16 colours are reserved.  In that case they will
                             be set to the standard VGA colours.

       Related options       -8   Convert to paletted image
                             -d   Specify dither type
                             -u   Use uniform palette




                   Copyright (c) 1990-1994 Handmade Software, Inc.          133 

       Examples              Convert the image colours.gif into a 16 colour PCX
                             file called colour16.pcx

                                alchemy colours.gif colour16.pcx -p -c16

                             Convert the image colours.tga into a 256 colour
                             GIF file called output.gif, reserving the first 16
                             colours.

                                alchemy colours.tga output.gif -g -c256 16














































       134         Copyright (c) 1990-1994 Handmade Software, Inc. 

       Dither                                                              -d


       Purpose               Specifies the type of dithering to apply to the
                             image.

       Syntax                -d[s] ditherType [perturbation]

       Parameters            If the -d is immediately followed by an 's', then
                             a serpentine raster is used.

                             ditherType:
                                  0:None
                                  1:Floyd-Steinberg
                                  2:Stucki
                                  3:Jarvis, Judice, & Ninke
                                  4:Stevenson and Arce
                                  5:Sierra Lite
                                  20:Halftone (clustered dot)
                                  21:Bayer (dispersed dot)
                                  22:Halftone 2 (clustered dot)
                             The default is Floyd-Steinberg.

                             perturbation:
                                  0 through 127
                             The default is 0.

       Comments              Dithering is used to reduce colour banding in an
                             image caused by the palette not having a perfect
                             match for every colour in the image.


                             Types 1 through 5 are all error-diffusion dithers.
                             Types 1 and 5 are the fastest of the diffusion
                             dithers, and they usually look the best on low
                             resolution devices like CRTs.  Types 2, 3, and 4
                             all tend to cause an image to appear more grainy
                             on low resolution output devices (such as CRTs).
                             However, they produce better results than types 1
                             or 5 on high-resolution, low colour output devices
                             such as laser printers or 1 bit CMYK plotters.


                             Type 22 is a digital halftone; this will produce
                             the most accurate grays on a laser printer, but
                             the image won't be as sharp as one produced by the
                             error-diffusion dithers.  Type 21 is a dispersed
                             dot ordered dither; it's only advantage over the
                             error-diffusion algorithms is speed.  Type 20 is
                             an additional halftone pattern.  It's similar to
                             type 22, but with a coarser screen.





                   Copyright (c) 1990-1994 Handmade Software, Inc.          135 

                             The -d option only has an effect if the number of
                             colours is being reduced or the image is being re-
                             mapped to a new palette.


                             Specifying a perturbation adds noise to the image,
                             which can help break up visible patterns
                             introduced by dithering.  The parameter specifies
                             the magnitude of the noise.  Perturbation has no
                             effect on dither types 20, 21, and 22.

                             Using a serpentine raster can also help to reduce
                             visible patterns introduced by dithering.  Using a
                             serpentine raster has no effect on dither types
                             20, 21, and 22.

                             In general we use -d1 when converting 24 bit
                             images to 8 bit paletted, and -ds3 when converting
                             colour images to black and white and 1 bit CMYK
                             (for sending to a laser printer or plotter).

       Examples              Convert the 256 colour file image.gif to a 16
                             colour PCX file using a uniform palette and no
                             dithering:

                                alchemy image.gif -p -c16 -d0 -u


                             Convert the true colour image sample.jpg into a
                             256 colour GIF file called sample.gif, using
                             Stucki dithering:

                                alchemy sample.jpg -g -d2


                             Convert the 256 colour image sample.gif into a one
                             bit black and white PCL file called sample.pcl,
                             using Jarvis, Judice, and Ninke dithering, a
                             serpentine raster, and a little noise:

                                alchemy sample.gif -P -b -c2 -ds3 20















       136         Copyright (c) 1990-1994 Handmade Software, Inc. 

       EGA Palette                                                         -E


       Purpose               Optimize the image quality for display on an EGA
                             board and monitor.

       Syntax                -E

       Comments              If you are converting images to display on an EGA
                             board and monitor this option will optimize the
                             image quality.

                             This option reduces the palette resolution to two
                             bits and automatically specifies the following:
                             -8 -c16 -z0 2 0.

       Limitations           The number of colours in an EGA palette must be
                             less than or equal to 16;  the number of colours
                             defaults to 16 but can be reduced by using the -c
                             option.

       Related options       -c   specify number of colours

       Example               Convert the image dave1.tga into dave1.pcx, a PCX
                             file with a palette optimized for EGA use:

                                alchemy dave1.tga -E -p





























                   Copyright (c) 1990-1994 Handmade Software, Inc.          137 

       False Colour                                                        -F


       Purpose               False colour an image using the palette from a
                             file.  The input image will be changed to use the
                             palette found in the specified filename but no
                             attempt at picking the best match will be done.

       Syntax                -F filename

       Parameter             filename:
                                  Any valid image file which contains a
                             palette.

       Comments              This feature can be used to add false colour to
                             monochrome images.

                             The output file is not dithered.

                             False colour may only be used with paletted input
                             files.

       Limitations           Cannot be combined with the spiff (-S) or match
                             palette (-f) options.

       Example               False colour the file scan.gif using the palette
                             from the file colorful.pcx, creating the GIF file
                             new.gif:

                                alchemy scan.gif new -F colorful.pcx -g


























       138         Copyright (c) 1990-1994 Handmade Software, Inc. 

       Gamma correction                                                    -G


       Purpose               Specify the gamma of an input, output, or palette
                             file and/or perform gamma correction.

       Syntax                -G gammaType gammaValue

       Parameters            gammaType:
                                  i:Specify input gamma
                                  o:Specify output gamma
                                  p:Specify gamma of palette

                             gammaValue:
                                  0.0 to 4.0

       Comments              To perform gamma correction, Alchemy needs to know
                             both the input and output gamma.  For some file
                             formats the gamma is known; if you're reading a
                             file with known gamma, such as JPEG, PICT,
                             PCPAINT, or a Targa file with a gamma field, you
                             don't need to specify the input gamma.  Likewise,
                             if you're writing a file which has a fixed gamma
                             you don't need to specify an output gamma.  Even
                             if reading or writing a file format which has a
                             known gamma you may override it by using the -Gi
                             or -Go option.


                             However, even if both input and output gamma are
                             known based on the input file and the output
                             format, you must still enable gamma correction for
                             any correction to take place; you can do this with
                             just '-G' (if you had specified input, output, or
                             palette gamma, this would be implied).  This is
                             because there are quite a few images around that
                             have specified or implied gammas that are wrong,
                             which could cause Alchemy to make matters worse
                             instead of better.


                             Typical gamma values are 1.0 for images from
                             Macintoshes and 2.2 for images from PCs.

       Examples              To convert the Mac PICT file test.pic, which has a
                             gamma of 1.0, to a PCX file for use on a PC (which
                             should have a gamma of 2.2), use:

                                alchemy test.pic -p -Gi1.0 -Go2.2







                   Copyright (c) 1990-1994 Handmade Software, Inc.          139 

                             In this example the input gamma could have been
                             omitted, as PICT files have an implied gamma of
                             1.0, but it's best to include it to reduce
                             confusion.

                             To convert the file image.tga, which has a gamma
                             of 2.2, to a GIF file for use on a Mac, matching
                             the palette test.pal which was created with a
                             gamma of 1.5:

                                alchemy image.tga -g -Gi2.2 -Go1.0 -Gp1.5    -
                                ftest.pal












































       140         Copyright (c) 1990-1994 Handmade Software, Inc. 

       Match Palette                                                       -f


       Purpose               Match the output to a palette read from a file.
                             The input image will be re-mapped to use the
                             palette found in the specified file.

       Syntax                -f filename

       Parameter             filename:
                                  Any valid image file which contains a palette

       Comments              Using the -f option will cause the output image to
                             be dithered (unless you specify no dithering by
                             using the -d0 option).

                             The -f option can be useful if you are combining
                             several images into a collage or want to match an
                             image to a pre-existing palette.  You can also
                             create a custom palette from scratch by using a
                             text editor and creating a .PAL file.

       Limitations           Cannot be combined with the spiff option (-S) or
                             the false colour option (-F).

                             The number of colours in the final image will be
                             equal to the number of colours in the palette
                             being read in.

                             The specified file must contain a palette (i.e.
                             cannot be true colour).

       Related options       -l   Generate palette file
                             -F   False colour
                             -d   Dither

       Examples              Convert the image bigimage.tif to a pcx file using
                             the palette from the file standard.pal:

                                alchemy bigimage.tif -p -f standard.pal

                             Convert the image colour.gif to a gif file called
                             colour2.gif using the palette from the file
                             newpal.gif:

                                alchemy colour.gif colour2 -fnewpal.gif -g










                   Copyright (c) 1990-1994 Handmade Software, Inc.          141 

       Negate                                                              -N


       Purpose               Changes the image to a negative.

       Syntax                -N

       Comments              This option is equivalent to a photographic
                             negative.  When used on black and white images
                             black is changed to white and white is changed to
                             black.  On colour images each of the Red, Green,
                             and Blue channels are inverted separately (so that
                             bright blue will become bright yellow).

       Example               Negate the file sample.gif, generating a GIF file
                             called negative.gif:

                                alchemy sample.gif negative -N -g






































       142         Copyright (c) 1990-1994 Handmade Software, Inc. 

       Palette                                                             -8


       Purpose               Force the output image to be paletted.

       Syntax                -8

       Comments              This option is -8 because paletted images are
                             typically 8 bits per pixel.

                             Alchemy defaults to the -8 option if the input
                             file is paletted or gray-scale.

                             Some file formats require files to be paletted;
                             for those formats the -8 option is assumed.  Some
                             file formats do not have a paletted variation; in
                             those cases the -8 option will be ignored if
                             specified.  Some file formats only allow gray-
                             scale files to be 8 bit; in those cases Alchemy
                             will ignore the -8 option if the image being
                             written is not gray-scale.

                             The actual number of bits per pixel is determined
                             by the -c option (below).

                             If the input file is true colour the output file
                             will be quantized and dithered (see the -c and -d
                             options below).

       Related options       -15  True colour output
                             -16  True colour output
                             -24  True colour output
                             -32  True colour output
                             -c   specify number of colours in image
                             -d   dither

       Examples              Convert the JPEG file bigimage.jpg into a paletted
                             TIFF file with 256 colours:

                                alchemy bigimage.jpg -8 -t

                             Convert the Targa file madonna.tga to a 16 colour
                             PCX file (note that the -8 option is implied by
                             the use of the  -c16 option):

                                alchemy madonna.tga -c16 -p










                   Copyright (c) 1990-1994 Handmade Software, Inc.          143 

       Palette Selection                                                   -z


       Purpose               Control how the palette is generated.  These
                             options only have an effect if the palette is
                             being generated by Alchemy using Heckbert's median
                             cut algorithm.

                             Most of the time you do not need to use these
                             options.  Alchemy will automatically generate the
                             best palette possible.  Contact us for further
                             information if you intend to use the -z option.

       Syntax                -z sortType [selectionType [swapType] ]


       Parameters            sortType:
                                  0:None
                                  1:Popularity
                                  2:Luminance (white to black)
                                  3:RGB
                                  4:Luminance (black to white)
                             The default is None.


                             selectionType:
                                  0:Mean
                                  1:Median
                                  2:Corner
                             The default is Mean.


                             See Appendix B, Colour and Dithering, for an
                             explanation of these choices.


                             swapType:
                                  0:None
                                  1:IBM (colour 0 is black, 7 is white)
                                  2:Macintosh (colour 0 is white, 255 is black)
                                  3:Sun (colour 0 is white, 1 is black)
                             The default is based on the file type being
                             written out (IBM for GIF, Macintosh for Mac PICT,
                             Sun for Sun Raster, and None for all others).












       144         Copyright (c) 1990-1994 Handmade Software, Inc. 

       Comments              The most common use for this option is to sort the
                             palette; in this case only a single parameter is
                             needed.

                             This option only affects palettes that are
                             generated by Alchemy.  To sort an existing palette
                             you can save the image as a true colour file (such
                             as HSI Raw, by using the -24 -r options) and then
                             convert that back to a paletted file, specifying
                             the desired sort type.  In most cases this will
                             not change the image (other than the palette
                             order); however if the palette had entries
                             representing colours that are nearly identical
                             then the image may be modified.

       Limitations           Note that it is not possible to specify a swapType
                             without first specifying both a sortType and a
                             selectionType.  See Appendix B, Colour and
                             Dithering, for more information.

       Example               Convert the file input.tga to a gif filed called
                             output.gif sorting the colours by luminance, using
                             the mean of the Heckbert box for the colour, and
                             moving the colours around so that the lightest
                             colour is colour 0 and the darkest colour is
                             colour 1.

                                alchemy input.tga output.gif -g -z4 0 3




























                   Copyright (c) 1990-1994 Handmade Software, Inc.          145 

       Spiff                                                               -S


       Purpose               Enhance the image contrast by stretching the pixel
                             colour values to the full 0 to 255 range.

       Syntax                -S spiffType

       Parameter             spiffType:
                                  a:Histogram stretching
                                  b:Histogram linearization
                                  c:Histogram stretching with black and white
                             ignored
                             The default is Histogram stretching.

       Comments              This command can be used if the image you are
                             converting is shifted in brightness or squished in
                             contrast.  This can happen if you scan or digitize
                             a very dark or very bright image.

                             The default type, histogram stretching, simply
                             insures that the image has pixels which are
                             distributed over the entire output range (0 to
                             255).

                             Histogram linearization insures that the
                             distribution of pixels over the output range is
                             linear.

                             Type c spiffing is identical to type a spiffing
                             except that the colours absolute black and
                             absolute white are ignored in the image.  This is
                             useful when you have images which have black
                             borders or white captions, since type a spiffing
                             would treat these as part of the image data and
                             not perform any spiffing.

                             Histogram linearization can produce significantly
                             better results than histogram stretching for some
                             images.  Generally you will want to try both types
                             to see which gives better results.

       Limitations           The -S option cannot be used at the same time as
                             the -b option when converting from a true colour
                             image.  A work around is to do the operation in
                             two steps, converting it to black and white first
                             and then spiffing the resulting image.









       146         Copyright (c) 1990-1994 Handmade Software, Inc. 

                             Using the spiff option at the same time as the
                             match palette, -f, or false colour, -F, options is
                             not allowed.  This is because the spiff option
                             would be performed before the palette is changed,
                             which would nullify the effects.  A work around is
                             to do the matching or false colouring first, and
                             then spiff the resultant image.


       Related options       -b   Black and White
                             -f   Match palette
                             -F   False colour image

       Examples              Convert the file gloomy.pcx into a PCX file called
                             better.pcx:

                                alchemy gloomy.pcx better.pcx -S -p

                             Do the same thing using histogram linearization
                             instead of histogram stretching:

                                alchemy gloomy.pcx better.pcx -Sb -p


































                   Copyright (c) 1990-1994 Handmade Software, Inc.          147 

       True Colour (15 bits)                                              -15


       Purpose               Force the output image to be true colour, 15 bits
                             (5 bits per component).

       Syntax                -15

       Comments              See the True Colour (24 bits) section, below.

       Related options       -8   Paletted output
                             -16  True colour output (16 bits)
                             -24  True colour output (24 bits)
                             -32  True colour output (32 bits)

       Example               Convert the GIF file test.gif into an
                             uncompressed, true colour 15 bit Targa file called
                             test.tga:

                                alchemy test.gif -a0 -15




































       148         Copyright (c) 1990-1994 Handmade Software, Inc. 

       True Colour (16 bits)                                              -16


       Purpose               Force the output image to be true colour, 16 bits
                             (5 bits each for red and blue, 6 for green).

       Syntax                -16

       Comments              See the True Colour (24 bits) section, below.

       Related options       -8   Paletted output
                             -15  True colour output (15 bits)
                             -24  True colour output (24 bits)
                             -32  True colour output (32 bits)

       Example               Convert the GIF file test.gif into an
                             uncompressed, true colour 16 bit Targa file called
                             test.tga:

                                alchemy test.gif -a0 -16




































                   Copyright (c) 1990-1994 Handmade Software, Inc.          149 

       True Colour (24 bits)                                              -24


       Purpose               Force the output image to be true colour, 24 bits
                             (8 bits per component).

       Syntax                -24

       Comments              This option is -24 because true colour images are
                             typically 24 bits per pixel.

                             Some file formats require files to be true colour;
                             for those formats the -24 option is assumed.  Some
                             file formats only have a paletted variation; in
                             those cases the -24 option will be ignored if
                             specified.

                             The file formats which may be either true colour
                             or paletted default to true colour if the input
                             file is true colour.

                             Certain file formats may only be paletted if the
                             images are gray-scale, in those cases Alchemy will
                             automatically switch to true colour if the output
                             image is colour.

                             Converting a paletted image to true colour will
                             not improve its quality or change its appearance.
                             The primary use of this option is to force an
                             image to be true colour when converting to a
                             format which allows either paletted or true
                             colour, but where the paletted variation is not
                             well supported (like the Targa image format).

                             If the file format you are converting to does not
                             have a 24 bit mode the closest true colour mode
                             available will be chosen, in the following order:
                             32 bit, 16 bit, 15 bit.

       Related options       -8   Paletted output
                             -15  True colour output (15 bits)
                             -16  True colour output (16 bits)
                             -32  True colour output (32 bits)

       Example               Convert the GIF file test.gif into an
                             uncompressed, true colour Targa file called
                             test.tga:

                                alchemy test.gif -a0 -24







       150         Copyright (c) 1990-1994 Handmade Software, Inc. 

       True Colour (32 bits)                                              -32


       Purpose               Force the output image to be true colour, 32 bits
                             (8 bits per component, 8 bits for the alpha
                             channel).

       Syntax                -32

       Comments              See the True Colour (24 bits) section, above.

       Related options       -8   Paletted output
                             -15  True colour output (15 bits)
                             -16  True colour output (16 bits)
                             -24  True colour output (24 bits)

       Example               Convert the GIF file test.gif into an
                             uncompressed, true colour 32 bit Targa file called
                             test.tga (the alpha channel will be empty):

                                alchemy test.gif -a0 -32



































                   Copyright (c) 1990-1994 Handmade Software, Inc.          151 

       Undercolour Removal                                                 -C


       Purpose               Control the undercolour removal process, colour
                             correction, and density correction for output
                             formats which use the CMYK colour space.  You will
                             probably want to use an undercolour removal file
                             when converting images to a format which uses the
                             CMYK colour space.

       Syntax                -C filename

       Parameter             filename:
                                  The name of the file which contains the
                             undercolour removal information

       Comments              The undercolour removal portion of the file is
                             compatible with the format used by Stork
                             Colorproofing B.V.  The format of this file is
                             described in Appendix G, Undercolour Removal
                             Files.

                             Sample undercolour removal files can be found in
                             the samples directory on the Alchemy distribution
                             disk or tape.  We are also developing additional
                             UCR files for use with specific devices; contact
                             us for more information.

       Example               Convert the file image.tga to an HP RTL file
                             called image.rtl using the undercolour removal
                             file sample.ucr:

                                alchemy image.tga --r4 -Csample.ucr























       152         Copyright (c) 1990-1994 Handmade Software, Inc. 

       Uniform Palette                                                     -u


       Purpose               Use a Uniform Palette.

       Syntax                -u

       Comments              Instead of using the Heckbert median cut algorithm
                             to generate a custom palette for the image, use a
                             palette with entries which are evenly distributed
                             in the RGB colour cube.

                             The advantage of using a uniform palette is that
                             it's faster than generating a custom palette.
                             However, this is at the expense of image quality
                             since the palette isn't generated based on image
                             content.

                             When just viewing a true colour image on a
                             paletted display a uniform palette is used.

                             The -c option can be used in conjunction with -u
                             to specify the size of the uniform palette; in
                             that case Alchemy will generate a palette with not
                             more than the specified number of colours (but not
                             less than 8).

       Limitations           The palette size will not necessarily match the
                             specified size, as the actual size must be the
                             product of three integers.  Alchemy picks integers
                             that roughly correspond to the sensitivity of the
                             human eye to red, green, and blue (30%, 59%, and
                             11%).

       Related options       -c   Specify number of colours
                             -d   Dither type

       Examples              Convert the file many.tga to a gif file using a
                             256 colour uniform palette:

                                alchemy many.tga -g -u

                             Convert the file many.tga to a gif file with up to
                             128 colours in a uniform palette:

                                alchemy many.tga -g -u -c128










                   Copyright (c) 1990-1994 Handmade Software, Inc.          153 

























































       154         Copyright (c) 1990-1994 Handmade Software, Inc. 

                                                                              7



       Scaling Options
       ------------------------------------------------------------------------


       Introduction          These options are all related to raster image
                             scaling.














































                   Copyright (c) 1990-1994 Handmade Software, Inc.          155 

       Flip Image                                                          -^


       Purpose               Flip image vertically (turn image upside-down)

       Syntax                -^ (caret)

       Comments              Causes the image to be turned upside-down.

                             May be combined with the mirror image option (see
                             below) to cause the image to be rotated 180
                             degrees.

       Related options       --^  Mirror image

       Example               Convert the Targa file head.tga to another Targa
                             file called tail.tga:

                                alchemy head.tga tail.tga -a -^





































       156         Copyright (c) 1990-1994 Handmade Software, Inc. 

       Mirror Image                                                       --^


       Purpose               Flip image horizontally (mirror image)

       Syntax                --^ (caret)

       Comments              Causes the image to be mirrored.

                             May be combined with the flip image option (see
                             above) to cause the image to be rotated 180
                             degrees.

       Related options       -^   Flip image

       Example               Convert the Targa file left.tga to another Targa
                             file called right.tga:

                                alchemy left.tga right.tga -a --^





































                   Copyright (c) 1990-1994 Handmade Software, Inc.          157 

       Offset Image                                                        -_


       Purpose               The offset image option changes the position of
                             the image on the page.  It only effects printer
                             and plotter formats.

       Syntax                -_ xOffset[units] yOffset[units] (underscore)

       Parameter             xOffset:
                                  The amount to shift the image horizontally.

                             yOffset:
                                  The amount to shift the image vertically.

                             units:
                                  The units each size parameter is in:
                                     p:Pixels
                                     i:Inches
                                     c:Centimeters
                                  units is optional; the default is pixels.
                             The units value must immediately follow the
                             appropriate offset parameter.

       Comments              The offset is measured from the upper left corner
                             for Calcomp, HP PCL, and HP RTL files and from the
                             lower left corner for EPS files.

       Limitations           Only works for those output options that support
                             an offset. These are Calcomp, EPS, HP PCL, and HP
                             RTL.

                             If you specify the offset in inches or centimeters
                             you must also specify a dots per inch value.

       Example               Convert the image temp.gif to an HP PCL file at
                             300 DPI, positioning it on the page 1 inch from
                             the top and 200 pixels from the left:

                                alchemy temp.gif -P -_ 200 1i -D300 300
















       158         Copyright (c) 1990-1994 Handmade Software, Inc. 

       Preserve Aspect Ratio                                               -+


       Purpose               Preserve aspect ratio when scaling.

       Syntax                -+ (plus)

       Comments              If specified with either the -X or -Y option
                             Alchemy will choose the other dimension to
                             preserve the aspect ratio of the image.

                             If specified in conjunction with both -X and -Y
                             Alchemy will use the values specified as a
                             bounding box, reducing one dimension if necessary
                             to preserve the image aspect ratio.

       Limitations           Does not pay attention to the pixel aspect ratio
                             values in the input image.

       Related options       -X   Scale image in horizontal dimension
                             -Y   Scale image in vertical dimension

       Examples              Change the size of the image toobig.gif so that
                             the width is 640 and the height is the correct
                             number to preserve the aspect ratio of the image
                             (the new image will be called notbig.gif):

                                alchemy toobig.gif notbig -X640 -+ -g

                             Do the same thing but guarantee that the image
                             will not be larger than 640 by 480:

                                alchemy toobig.gif notbig -X640 -Y480 -+     -g


                             Do the same thing but use better quality scaling:

                                alchemy toobig.gif notbig -Xb640 -Yb480 -+   -g


















                   Copyright (c) 1990-1994 Handmade Software, Inc.          159 

       Scale Image in Horizontal Direction                                 -X


       Purpose               Scale the horizontal dimension of the image to the
                             specified size.

       Syntax                -X[scaleType] size[units]

       Parameters            scaleType:
                                  The type of scaling to use:
                                     a:Nearest Neighbor
                                     b:Averaging/Linear Interpolation
                                     c:Lanczos2
                                     d:Lanczos3
                                  scaleType is optional; the default is Nearest
                             Neighbor.  The higher the scale type the higher
                             the quality (and the longer the processing time).

                             size:
                                  The size of the output image in the
                             horizontal dimension.

                             units:
                                  The units the size parameter is in:
                                     p:Pixels
                                     i:Inches
                                     c:Centimeters
                                     x:Factor
                                  units is optional; the default is pixels.
                             The units value must immediately follow the size
                             parameter.

       Comments              Nearest neighbor type scaling is faster than the
                             other types but introduces aliasing (which reduces
                             image quality).  The highest quality scaling
                             supported is lanczos3, but it takes much longer
                             than averaging/linear interpolation and usually
                             doesn't produce significantly better results.


                             Specifying a units value of x causes the size
                             parameter to be treated as a scale factor;  e.g. -
                             X 2.5x scales the image by a factor of 2.5 in the
                             X direction.


                             If you specify a units for the image size in
                             inches or centimeters you must specify a dots per
                             inch value for the output image.







       160         Copyright (c) 1990-1994 Handmade Software, Inc. 

       Limitations           All of the scale types other than nearest neighbor
                             give much better results than nearest neighbor
                             scaling, but they are slower and require a new
                             palette to be generated for paletted output files
                             (you can force alchemy to use the original palette
                             by using the -f option and specifying the original
                             image as the palette file).

       Related options       -Y   Scale in vertical dimension
                             -+   Preserve aspect ratio
                             -D   Specify image resolution

       Examples              Scale the input image, test.gif, to 640 by 480
                             using good quality scaling, calling the output
                             file test2.gif:

                                alchemy test.gif test2.gif -Xb640 -Yb480     -g

                             Scale the input image, big.tga, using fast scaling
                             to an image which is 320 pixels across and the
                             same aspect ratio as the input image, calling the
                             output file out.tga:

                                alchemy big.tga out -X320 -+ -a

                             Scale the input image, oddsize.gif, using the
                             highest quality scaling, to an image which is no
                             larger than 640x480, but has the same aspect ratio
                             as the original image, calling the output image
                             new.gif:

                                alchemy oddsize.gif new.gif -Yd480 -Xd640    -+
                                -g

                             Do the same thing as the previous example, but
                             retain the same palette:

                                alchemy oddsize.gif new.gif -Yd480 -Xd640    -+
                                -g -f oddsize.gif

                             Scale the input image, test.gif, to 2.5 times its
                             original size in both dimensions using good
                             quality scaling, calling the output file
                             test2.gif:

                                alchemy test.gif test2 -Xb2.5x -Yb2.5x -g

                             Scale the input image, silly.tga, to 1/3 its
                             original size in the X dimension and 1/4 the
                             original size in the Y dimension, using low
                             quality scaling in the X dimension and very high
                             quality scaling in the Y dimension, calling the
                             output file test.tga:

                                alchemy silly.tga test -a -Xa.33x -Yd0.25x

                   Copyright (c) 1990-1994 Handmade Software, Inc.          161 

                             Scale, using type b scaling, the input image,
                             test.jpg, to 3" x 4.5" inches writing a 300 DPI HP
                             PCL file:

                                alchemy test.jpg -P -Xb3i -Yb4.5i
                                     -D300 300

                             Print all JPEG images in the current directory to
                             an HP LaserJet at 300 DPI, using dither type 22,
                             scaling the images to fill the page and preserving
                             aspect ratio (we use 8.16" x 10.66" inches as the
                             printable area since the printer has a 1/6" border
                             on all four edges):

                                alchemy -- *.jpg -P -Xb8.16i -Yb10.66i -+
                                     -D300 300 -d22








































       162         Copyright (c) 1990-1994 Handmade Software, Inc. 

       Scale Image in Vertical Direction                                   -Y


       Purpose               Scale the vertical dimension of the image to the
                             specified size.

       Syntax                -Y[scaleType] size[units]

       Parameters            scaleType:
                                  The type of scaling to use:
                                     a:Nearest Neighbor
                                     b:Averaging/Linear Interpolation
                                     c:Lanczos2
                                     d:Lanczos3
                                  scaleType is optional; the default is Nearest
                             Neighbor.  The higher the scale type the higher
                             the quality (and the longer the processing time).

                             size:
                                  The size of the output image in the vertical
                             dimension.

                             units:
                                  The units the size parameter is in:
                                     p:Pixels
                                     i:Inches
                                     c:Centimeters
                                     x:Factor
                                  units is optional; the default is pixels.
                             The units value must immediately follow the size
                             parameter.

       Comments              Nearest neighbor type scaling is faster than the
                             other types but introduces aliasing (which reduces
                             image quality).  The highest quality scaling
                             supported is lanczos3, but it takes much longer
                             than averaging/linear interpolation and usually
                             doesn't produce significantly better results.


                             Specifying a units value of x causes the size
                             parameter to be treated as a scale factor;  e.g. -
                             Y 2.5x scales the image by a factor of 2.5 in the
                             Y direction.


                             If you specify a units for the image size in
                             inches or centimeters you must specify a dots per
                             Inch value for the output image.







                   Copyright (c) 1990-1994 Handmade Software, Inc.          163 

       Limitations           All of the scale types other than nearest neighbor
                             give much better results than nearest neighbor
                             scaling, but they are slower and require a new
                             palette to be generated for paletted output files
                             (you can force alchemy to use the original palette
                             by using the -f option and specifying the original
                             file name).

       Related options       -X   Scale in horizontal dimension
                             -+   Preserve aspect ratio
                             -D   Specify image resolution

       Examples              See the -X option, Scale Image in Horizontal
                             Direction, above, for examples.










































       164         Copyright (c) 1990-1994 Handmade Software, Inc. 

       Specify Image Aspect Ratio                                          -D


       Purpose               Specify aspect ratio for the output image.

       Syntax                -D aspectRatio

       Parameter             aspectRatio:
                                  The percentage of the width of a pixel to its
                             height.

       Comments              This option does not actually change the aspect
                             ratio of the image, it just adds the aspect ratio
                             value to the output file.  This is important when
                             trying to export the image to software which
                             expects this information.


                             The aspect ratio of an image is the ratio of the
                             width of a single pixel to the height of a single
                             pixel.  (So to specify an aspect ratio of 5:6 use
                             -D 83, since (5/6)*100 is 83).


                             Alchemy attempts to preserve the aspect ratio
                             value when converting images whenever one is found
                             in the input image, but since so few file formats
                             have aspect ratio information this hardly ever
                             happens.


                             To write an output image without aspect ratio
                             information specify an aspect ratio of 0 (zero).


                             This option also has an effect when using the MS-
                             DOS version of Image Alchemy and displaying
                             images.

       Limitations           It is not possible to specify both an aspect ratio
                             and a dots per inch value for an image.  This is
                             because specifying a dots per inch value implies
                             an aspect ratio.


                             Many file types do not have an aspect ratio value;
                             specifying one when writing such a file type will
                             have no effect.

       Related options       -D   Specify resolution






                   Copyright (c) 1990-1994 Handmade Software, Inc.          165 

       Examples              You are converting a 640x350 IBM EGA PCX image
                             called ega.pcx (which has an aspect ratio of
                             35:48) to a TIFF image and you want the TIFF image
                             to have the correct aspect ratio value (so that an
                             intelligent TIFF reader will correctly interpret
                             the image).  Note that the value of 73 is
                             (35/48)*100:

                                alchemy ega.pcx -D 73 -t

                             The resulting image will still be 640x350, but the
                             TIFF file now contains the information that the
                             pixels are not square (and in fact are 35:48).

                             If you had instead wanted to convert the image to
                             a 640 by 480 image (with square pixels) you could
                             have used:

                                alchemy ega.pcx -Y480 -D100 -t

                             The -D option isn't really needed here, since any
                             software reading the TIFF file will assume that if
                             there is no aspect ratio specified the pixels are
                             square.
































       166         Copyright (c) 1990-1994 Handmade Software, Inc. 

       Specify Image Resolution                                            -D


       Purpose               Specify image resolution in dots per inch for the
                             output image.

       Syntax                -D dotsPerInchX dotsPerInchY

       Parameters            dotsPerInchX:
                                  The resolution of the image in the X
                             direction in dots per inch.

                             dotsPerInchY:
                                  The resolution of the image in the Y
                             direction in dots per inch.

       Comments              You must specify both dotsPerInchX and
                             dotsPerInchY, even if they are the same.


                             When converting from a raster file this command
                             does not actually change the resolution of the
                             image, it just adds the resolution fields to the
                             output image.  This is important when trying to
                             import the image into software which expects this
                             information.  For example, Microsoft Word is much
                             more likely to give the expected results when
                             importing a TIFF image for printing on a laser
                             printer if the image has a resolution of 300 dpi.


                             Reasonable values to use for dotsPerInch include
                             72 (the resolution of a 13 inch monitor displaying
                             640x480) and 300 (the resolution of most laser
                             printers).


                             To write an output image without resolution
                             information specify a resolution of 0 0 (zero
                             zero).


                             Alchemy will preserve this information when
                             converting files whenever possible.


                             Many file types do not have an resolution value;
                             specifying one when writing such a file type will
                             only affect the raster scaling functions.


                             This option also has an effect when using the MS-
                             DOS version of Image Alchemy and displaying
                             images.


                   Copyright (c) 1990-1994 Handmade Software, Inc.          167 

       Limitations           It is not possible to specify both an aspect ratio
                             and a dots per inch value for an image.  This is
                             because specifying a dots per inch value
                             automatically implies an aspect ratio.


                             This option is ignored when writing a file format
                             which does not have image resolution.

       Related options       -D   Specify aspect ratio

       Examples              Convert the Targa file input.tga to a TIFF file
                             called output.tif, specifying that the resolution
                             of the image in the TIFF file is 300 dpi by 300
                             dpi:

                                alchemy input.tga output -t -D 300 300

                             Convert the file scan.tif to a DCX variation of a
                             PCX file, scaling the output image to 1500 by 750
                             (preserving the image's aspect ratio) and setting
                             the resolution to 200 DPI by 100 DPI (this is
                             useful if you will be faxing the image using a fax
                             card):

                                alchemy scan.tif -p1 -X1500 -Y750 -+ -D 200 100






























       168         Copyright (c) 1990-1994 Handmade Software, Inc. 

                                                                              8



       Viewing Options


       MS-DOS Only
       ------------------------------------------------------------------------



       Display hardware      Image Alchemy can display images on properly
                             equipped MS-DOS based computers.

                             Depending on the hardware you have installed,
                             Alchemy supports the following display
                             resolutions:  640x480, 800x600, 1024x768, and
                             1280x1024.

                             Also depending on the hardware, Alchemy supports
                             the following display depths:  8 bit, 15 bit, 16
                             bit, and 24 bit (for 256, 32768, 65536, and
                             16,777,216 colours, respectively).

                             In addition, Alchemy supports the standard VGA
                             mode of 320x200x256, the quasi-standard VGA mode
                             of 360x480x256, and the common SVGA mode of
                             640x400x256.


                             When instructed to display an image, Alchemy
                             automatically detects which type of display board
                             you have installed.  If there are multiple display
                             boards installed in your computer then Alchemy
                             will display images on the first board it finds,
                             searching in the following order:

                                Western Digital based 8514/A board
                                AI compatible 8514/A board
                                XGA board
                                VESA compatible SVGA board
                                Other SVGA board


         Western Digital     8514/A boards which are equipped with the Western
                  8514/A     Digital chipset are automatically recognized by
                             Alchemy.  Depending on the model board and the
                             amount of memory installed, 640x480x256,
                             1024x768x256, and 1280x1024x256 modes are
                             available.





                   Copyright (c) 1990-1994 Handmade Software, Inc.          169 

               AI 8514/A     Alchemy requires AI to be installed to use 8514/A
                             displays which aren't based on the Western Digital
                             chipset.  In addition to 8514/A boards Alchemy
                             should also be able to display on other AI
                             compatible boards, such as 340x0 based boards;
                             however this has not been tested.  For AI based
                             boards the only resolution available is
                             1024x768x256.

                     XGA     Alchemy automatically detects the presence of an
                             XGA or XGA2 board and will use it when displaying
                             images.  The display modes available for XGA
                             boards are 640x480x256, 1024x768x256, and
                             640x480x65536 (the actual modes available vary
                             with the model XGA board installed and the amount
                             of memory available).

                    VESA     The best support for SVGA boards is available for
                             VESA compatible SVGA boards.  VESA is an SVGA
                             standard which allows application software, such
                             as Image Alchemy, to interrogate the SVGA board to
                             determine which display modes are available.


                             Some SVGA boards have VESA support built directly
                             into the BIOS found on the board; in this case
                             Alchemy will automatically detect the VESA driver
                             and use it.  Other SVGA boards require a software
                             driver to be installed; these drivers are usually
                             found on the floppy disks which came with your
                             SVGA board (typically the driver is called
                             VESA.EXE).


                             If you can't find a driver on the diskettes and
                             the documentation does not explicitly mention that
                             VESA support is built into the BIOS you might call
                             the manufacturer to see if a VESA driver is
                             available.


                             VESA drivers are currently available for VGA
                             boards using chipsets from Cirrus Logic, ATI
                             Technologies, Chips and Technologies, Everex
                             Systems, Genoa Systems, Paradise Logic, Sigma
                             Designs, STB Systems, Tecmar, Headland Technology
                             (Video 7), Orchid Technology, Appian Technology,
                             Trident Microsystems, and Oak Technology.








       170         Copyright (c) 1990-1994 Handmade Software, Inc. 

              Other SVGA     If Alchemy cannot find a VESA SVGA board it
                             attempts to determine what kind of SVGA board is
                             present.  If Alchemy can identify the type of SVGA
                             board installed either a 640x400x256 or
                             640x480x256 mode will be available.

                             SVGA boards which are known to work with Alchemy
                             include Paradise, Tseng Labs 3000 & 4000, Video 7,
                             Trident, and Everex chipset based VGA Boards.


                     VGA     The 320x200x256 mode is a standard IBM VGA mode
                             and will work on all VGA boards.  The 360x480x256
                             is a non-standard VGA mode which should also work
                             on all VGA boards.

       Display               Unless you explicitly specify a resolution after
       Resolution            the view command, Alchemy automatically uses the
                             lowest resolution mode which will display the
                             entire picture.


                             Alchemy can be told to not use above a particular
                             resolution by setting the environment variable
                             alchemy to the largest horizontal resolution to be
                             used.


                             For example, if your monitor can only display up
                             to 800x600 pixels, but your VESA compatible VGA
                             board can display up to 1024x768 pixels.  You
                             would set alchemy=800, to insure that Alchemy
                             won't try to use the 1024x768 mode.  You may want
                             to add this command to your autoexec.bat file, so
                             that it is automatically set when your computer is
                             turned on.


                             When an image is displayed that is smaller than
                             the screen resolution the image will be centered
                             in the display and the area around the image will
                             be set to the darkest colour in the image (which
                             is usually black).













                   Copyright (c) 1990-1994 Handmade Software, Inc.          171 

       Offset View                                                         -_


       Purpose               The offset view option changes the position of the
                             image on the screen during viewing.

       Syntax                -_ xOffset yOffset (underscore)

       Parameter             xOffset:
                                  Number of pixels to shift the image
                             horizontally.

                             yOffset:
                                  Number of pixels to shift the image
                             vertically.

       Examples              View moving the image up 100 pixels:

                                alchemy madonna.gif -v -_ 0 -100

                             View moving the image to the right 200 pixels and
                             down 50 pixels:

                                alchemy madonna.gif -v -_ 200 50
































       172         Copyright (c) 1990-1994 Handmade Software, Inc. 

       View Image                                                          -v


       Purpose               View file.

       Syntax                -v horizontalResolution

       Parameter             horizontalResolution:
                                  320:Use 320x200 mode
                                  360:Use 360x480 mode
                                  640:Use 640x480 mode
                                  800:Use 800x600 mode
                                  1024:Use 1024x768 mode
                                  1280:Use 1280x1024 mode

       Comments              If displaying on a Western Digital chipset 8514/A
                             or VESA compatible VGA board, an optional
                             parameter may follow the -v command.  This
                             parameter specifies horizontal resolution and may
                             be 320, 360, 640, 800, 1024, or 1280.  The default
                             is to use the lowest resolution which can fit the
                             entire image.  You may set the environment
                             variable alchemy to indicate the highest
                             horizontal resolution you want Alchemy to use when
                             displaying images (for example, set alchemy=800 to
                             will cause Alchemy to use only 640x480 and 800x600
                             resolutions when displaying images).

                             If the image is true colour, a uniform palette
                             will be used and the image will be dithered
                             (dithering may be disabled by use of the -d
                             option, see above).  See Appendix B, Colour and
                             Dithering, for more information.

       Related options       -V   Reduce image to fit display

       Example               View the image madonna.gif:

                                alchemy madonna.gif -v

















                   Copyright (c) 1990-1994 Handmade Software, Inc.          173 

       View Image in True Colour Mode                                     --v


       Purpose               View file using 15, 16, or 24 bits/pixel mode.
                             This allows true colour images to be viewed
                             without dithering to a uniform palette.

       Syntax                --v horizontalResolution

       Parameter             horizontalResolution:
                                  640:Use 640x480 mode
                                  800:Use 800x600 mode
                                  1024:Use 1024x768 mode
                                  1280:Use 1280x1024 mode

       Comments              Requires a VESA compatible SVGA board or a Tseng
                             4000, S3, ATI, Genoa, Speedstar24, or a
                             Speedstar24X with an appropriate DAC and at least
                             1 Megabyte of memory on the SVGA board.


                             Resolutions above 640x480 are only supported by
                             SVGA boards with a VESA driver.  640x480 mode is
                             supported for various SVGA boards with sufficient
                             memory and the correct DAC.


                             Alchemy automatically picks the highest colour
                             resolution which will fit the image you are trying
                             to view.  For example, if your  SVGA boards
                             supports 800x600x15 bit and 640x480x24 bit,
                             Alchemy will use the 640x480x24 bit mode when
                             viewing images which are 640x480 and smaller and
                             the 800x600 mode when viewing larger images.  You
                             can of course override this by giving Alchemy a
                             resolution parameter after the view command (for
                             example, --v 640, to view in 640x480x24 bit mode).
                             You may also set the environment variable alchemy
                             to indicate the highest horizontal resolution you
                             want Alchemy to use when displaying images (for
                             example, set alchemy=800 to will cause Alchemy to
                             use only 640x480 and 800x600 resolutions when
                             displaying images).


                             If the image being displayed is a 24 bits per
                             pixel true colour image, and the display mode is
                             15 or 16 bits per pixel, the image will be
                             dithered (dithering may be disabled by use of the
                             -d option, see above).

       Example               View madonna.tga:

                                alchemy madonna.tga --v


       174         Copyright (c) 1990-1994 Handmade Software, Inc. 

       View Scaled Image                                                   -V


       Purpose               View image while scaling image to fit on monitor
                             and correcting aspect ratio.

       Syntax                -V horizontalResolution

       Parameter             horizontalResolution:
                                  320:Use 320x200 mode
                                  360:Use 360x480 mode
                                  640:Use 640x480 mode
                                  800:Use 800x600 mode
                                  1024:Use 1024x768 mode
                                  1280:Use 1280x1024 mode

       Comments              If displaying on a Western Digital chipset 8514/A
                             or VESA compatible VGA board, an optional
                             parameter may follow the -v command.  This
                             parameter specifies horizontal resolution and may
                             be 320, 360, 640, 800, 1024, or 1280.  The default
                             is to use the lowest resolution which can fit the
                             entire image.  You may set the environment
                             variable alchemy to indicate the highest
                             horizontal resolution you want Alchemy to use when
                             displaying images (for example, set alchemy=800 to
                             will cause Alchemy to use only 640x480 and 800x600
                             resolutions when displaying images).

                             This command will scale the image and correct the
                             aspect ratio of the image by removing rows and/or
                             columns from the image.

                             Note that this option can also be useful for
                             displaying images which are not larger than the
                             screen but which have an aspect ratio different
                             than the display.

       Limitations           Alchemy assumes that the aspect ratio of a display
                             pixel is 1:1 when in 640x480, 800x600, 1024x768,
                             and 1280x1024 modes, 5:6 when in 640x400 mode and
                             320x200 modes, and 16:9 in 360x480 mode.


                             If not otherwise specified by using the -D option
                             or in the file, Alchemy assumes that the aspect
                             ratio of pixels in 640x400 images and 320x200
                             images is 5:6 and the aspect ratio of pixels in
                             640x350 images is 35:48.  You can override any of
                             these assumptions with the -D option.






                   Copyright (c) 1990-1994 Handmade Software, Inc.          175 

                             Don't worry if this is confusing; in practice
                             Alchemy deals with everything automatically if you
                             use the -V option.  However, there is a problem
                             with displaying 320x400 IFF files; see Appendix A,
                             Answers to Frequently Asked Questions, for more
                             information.

       Related options       -D   Specify image resolution
                             -v   View image

       Example               View madonna.gif:

                                alchemy madonna.gif -V











































       176         Copyright (c) 1990-1994 Handmade Software, Inc. 

       View Scaled Image in True Colour Mode                              --V


       Purpose               View image in 15 bit mode while scaling image to
                             fit on monitor and correcting aspect ratio.

       Syntax                --V horizontalResolution

       Parameter             horizontalResolution:
                                  640:Use 640x480 mode
                                  800:Use 800x600 mode
                                  1024:Use 1024x768 mode
                                  1280:Use 1280x1024 mode

       Comments              Requires a Tseng 4000, S3, ATI, Genoa, or
                             Speedstar24 or an appropriate VESA compatible SVGA
                             board with an appropriate DAC and 1 Megabyte of
                             memory on the SVGA board.


                             Resolutions above 640x480 are only supported by
                             SVGA boards with a VESA driver.  640x480 mode is
                             supported for various SVGA boards with sufficient
                             memory and the correct DAC.


                             Alchemy automatically picks the highest colour
                             resolution which will fit the image you are trying
                             to view.  For example, if your  SVGA board
                             supports 800x600x15 bit and 640x480x24 bit,
                             Alchemy will use the 640x480x24 bit mode when
                             viewing images which are 640x480 and smaller and
                             the 800x600 mode when viewing larger images.  You
                             can of course override this by giving Alchemy a
                             resolution parameter after the view command (for
                             example, --v 640, to view in 640x480x24 bit mode).
                             You may also set the environment variable alchemy
                             to indicate the highest horizontal resolution you
                             want Alchemy to use when displaying images (for
                             example, set alchemy=800 will cause Alchemy to use
                             only 640x480 and 800x600 resolutions when
                             displaying images).


                             If the image being displayed is a 24 bits per
                             pixel true colour image, and the display mode is
                             15 or 16 bits per pixel, the image will be
                             dithered (dithering may be disabled by use of the
                             -d option, see above).


                             This command will scale the image and correct the
                             aspect ratio of the image by removing rows and/or
                             columns from the image.


                   Copyright (c) 1990-1994 Handmade Software, Inc.          177 


                             Note that this option can also be useful for
                             displaying images which are not larger than the
                             screen but which have an aspect ratio different
                             than the display.

       Limitations           The same limitations as for scaled 8 bit viewing
                             apply (see above).

       Related options       -D   Specify image resolution
                             --v  View image in True colour mode

       Example               View big.jpg in true colour 640x480 mode, reducing
                             the image to fit on the screen:

                                alchemy big.jpg --V 640








































       178         Copyright (c) 1990-1994 Handmade Software, Inc. 

                                                                              9



       Tutorial and Examples
       ------------------------------------------------------------------------


       Introduction          This section gives a sample session of using Image
                             Alchemy.  It is assumed that you have installed
                             Alchemy as instructed by the installation section
                             of the manual.  The sample image file, sample.jpg,
                             which can be found in the \samples directory on
                             the distribution disk or tape, must be in the
                             current directory.

                             Several of the examples include viewing commands.
                             Viewing is not possible on non-MS-DOS versions of
                             Image Alchemy (and viewing requires the
                             installation of a compatible SVGA board).

       Examples              We will use the sample.jpg image supplied in the
                             \samples directory.  The first step is to copy
                             this into the directory with Alchemy.

                                copy samples\sample.jpg .

                                (cp samples/sample.jpg . for UNIX systems)

                             Now we will convert this JPEG file to a GIF file.
                             Notice that we don't have to specify an output
                             file name.  Alchemy will automatically generate
                             the name sample.gif.

                                alchemy sample.jpg -g

                             We can then view this GIF file using Image Alchemy
                             (assuming you have a compatible SVGA card):

                                alchemy sample.gif -v

                             To convert the sample.gif file to a PCX file
                             called test1.pcx do the following:

                                alchemy sample.gif test1.pcx -p

                             You can now view this file by doing:

                                alchemy test1 -v







                   Copyright (c) 1990-1994 Handmade Software, Inc.          179 

                             Note here that Alchemy automatically added the
                             extension .pcx since none was supplied.

                             Let us now convert the test1.pcx file to a small
                             TIFF file called test1.tif; we will scale the TIFF
                             file to be 200x100 pixels.  To perform the scaling
                             we will use -X and -Y options:

                                alchemy test1.pcx -t -Xb200 -Yb100

                             In this case we specified that Alchemy should use
                             type B scaling.  This is a good scaling type to
                             use for general purpose scaling (type A scaling is
                             faster but not as good a quality, whereas Type C
                             and Type D scaling are better quality but slower).

                             You can now view this TIFF file by using:

                                alchemy test1.tif -v

                             If you had wanted to view it using the standard
                             VGA mode 320x200 you could have used:

                                alchemy test1.tif -v320

                             To convert this TIFF file to a gray-scale PCX file
                             use

                                alchemy test1.tif -b -p -o

                             The -b option indicates black and white and the -o
                             option tells Alchemy that it is okay to overwrite
                             the existing test1.pcx file.

                             You can now view this PCX file by using:

                                alchemy test1.pcx -v

                             To convert the JPEG file sample.jpg to a Targa
                             file called sample.tga use the following command:

                                alchemy -a sample.jpg

                             To convert the 24 bit Targa file sample.tga to a
                             256 colour GIF file called new.gif:

                                alchemy -g sample.tga new.gif

                             To convert the 256 colour GIF file, new.gif, to a
                             64 colour PCX file called new.pcx:

                                alchemy -p -c64 new.gif

                             To view the GIF file new.gif (only applicable on
                             IBM PCs with appropriate SVGA board):

       180         Copyright (c) 1990-1994 Handmade Software, Inc. 

                                alchemy -v new.gif

                             To convert sample.jpg to a black and white, two
                             colour GIF file use a text editor to create a file
                             called BW.PAL which contains the following:

                                PAL
                                2
                                0 0 0
                                255 255 255

                             then:

                                alchemy -g sample.jpg -f bw.pal

                             (Alternatively, you could have said alchemy -g
                             sample.jpg -b -c2, but that wouldn't have
                             demonstrated the -f option).

                             To view the resulting file in 320x200x256 mode,
                             scaling the image to fit the display:

                                alchemy -V320 sample.gif

                             To create an LZW compressed TIFF file called
                             new.tif which is 320x240 from the Targa file
                             created earlier, using good quality scaling:

                                alchemy sample.tga -t1 -Xb320 -+ new.tif



























                   Copyright (c) 1990-1994 Handmade Software, Inc.          181 

























































       182         Copyright (c) 1990-1994 Handmade Software, Inc. 

                                                                              A



       Answers to Frequently Asked Questions
       ------------------------------------------------------------------------



                Question     When I view a JPEG compressed image on my VGA
                             board it looks much worse than when I first
                             convert it to a GIF file and then view it.  Why is
                             this?

                  Answer     To save time Alchemy automatically uses a uniform
                             palette when you are just viewing a true colour
                             image.  When converting to a different file format
                             Alchemy uses Heckbert quantization to generate a
                             palette.  The difference in image quality is the
                             difference between using a uniform palette and an
                             optimum palette.  See Appendix B, Colour and
                             Dithering, for more information on palette
                             generation.


                Question     Why is decompressing or compressing a JPEG image
                             so slow?

                  Answer     There are a large number of calculations that have
                             to be done during JPEG compression.  This is an
                             inherent limitation of JPEG compression.  Image
                             Alchemy has been optimized quite a bit to reduce
                             the number of calculations, and we are working to
                             further reduce the number of calculations.  If you
                             are transferring files over modems or storing them
                             on slow media (tape) the compression times are
                             usually more than made up for by the decrease in
                             transmission or retrieval times.


















                   Copyright (c) 1990-1994 Handmade Software, Inc.          183 

                Question     I'm using Alchemy to print an image.  The print
                             out is much darker than the original image.  Why
                             is this?

                  Answer     Many hard copy output devices, including laser
                             printers, ink jet printers, and ink jet plotters,
                             have a property known as dot gain.  Dot gain
                             causes more toner or ink to be placed on the paper
                             than is expected.  This is caused by the fact that
                             the individual pixels being output are round, and
                             in order to completely fill in a square grid with
                             round pixels the round pixels have to be larger
                             than the square (in fact the circle has /2 times
                             as much area as the square).  In this example of a
                             single pixel the black area represents the "extra"
                             toner or ink that is being printed:




                             You can compensate for dot gain by adjusting the
                             gamma of the image during the conversion process.
                             The exact gamma value will depend on the output
                             device, but in general, specifying an output gamma
                             of 2.0 produces good results (-Gi 1.0 -Go 2.0 on
                             the command line will accomplish this).  (If you
                             are using a UCR file you can also compensate for
                             dot gain by using a UCR file with a gamma of 2.0).


                             It is not as necessary to compensate for dot gain
                             when printing at a resolution less than the
                             printer's maximum resolution.  This is because the
                             output device automatically groups individual
                             pixels together to make the output pixel, which
                             reduces the amount of extra toner or ink being
                             deposited on the page, as in this example of
                             printing a 150 DPI pixel on a 300 DPI device:



                             The same is true if you are using dithering types
                             20 and 22 (since those dithering types cluster the
                             dots).












       184         Copyright (c) 1990-1994 Handmade Software, Inc. 

                Question     How do I capture screens when running in Microsoft
                             Windows (or on the Macintosh)?

                  Answer     To capture the current screen when running
                             Microsoft Windows press PRINT SCREEN.  This copies
                             a bitmap of the entire screen onto the clipboard.
                             Then open the Paintbrush program which comes with
                             Windows and select Paste to copy the image from
                             the clipboard.  The image may now be saved as a
                             BMP file which Alchemy can convert.

                             On the Macintosh press Command-Shift-3.  This will
                             create a file on your hard disk called Picture n,
                             where n is a number which starts at 1 and
                             increases by 1 every time you capture another
                             screen.  This file can be converted by Alchemy.


                Question     Why can't my favorite desktop publishing package
                             read the TIFF file I wrote with Image Alchemy?

                  Answer     TIFF is an extremely versatile standard; it can
                             handle anything from 1 bit images to full colour
                             images with an alpha channel.  Also, TIFF allows
                             many different types of compression.
                             Unfortunately this versatility means that it's
                             difficult for a single piece of software to be
                             able to read in every valid TIFF file.



                             If the software specifies the classes of TIFF it
                             can read, you can force Alchemy to write out a
                             specific TIFF class by using the following
                             options:
                                class B:-8 -b -c2 -t2
                                class G:-8 -b -t1
                                class P:-8 -t1
                                class R:-24 -t1

                             Class B is black and white, Class G is gray-scale,
                             Class P is paletted, and Class R is true colour.














                   Copyright (c) 1990-1994 Handmade Software, Inc.          185 

                             If the supported classes are not specified,
                             experiment with various combinations of -24, -8, -
                             b, and -c.  In this case it is usually best to use
                             no compression (-t0) while experimenting with the
                             other options, as many TIFF readers have
                             difficulty with compressed files.  When you find a
                             set of options that work, then you can try various
                             compression modes to save space.  Be aware that
                             using the -b option will force the output file to
                             be gray-scale and you will lose the colour
                             information in the file (most desktop publishing
                             programs only have support for gray-scale TIFF
                             files).


                             You may also have to use the -Dn n option to
                             specify the resolution of the image (this is
                             especially true when converting from a file format
                             which does not have a value for image resolution).
                             You can generally tell if this is necessary
                             because the program you are using to read in the
                             TIFF file will claim that the file is unreasonably
                             large or small.  Usually, if you are using a 300
                             DPI Laser Printer you want to make the TIFF file
                             300 DPI x 300 DPI (-D 300 300).


                             If you would like further information specific to
                             using Image Alchemy with your word processor or
                             desktop publishing program please contact us; we
                             will be maintaining a list of how to make Alchemy
                             work with other software packages.  Similarly if
                             you figure out how to import files into a specific
                             package let us know and we will add your tips to
                             our documentation.


                Question     Why can't my paint package read the Targa file I
                             wrote with Image Alchemy?

                  Answer     Some software which reads Targa files cannot
                             handle compressed files.  In addition, some
                             software can read true colour Targa files, but
                             cannot read paletted or gray-scale files.  Image
                             Alchemy can be forced to write out a true colour
                             file by using the -24 option.










       186         Copyright (c) 1990-1994 Handmade Software, Inc. 

                Question     When I convert a GIF file to a JPEG file and then
                             back to a GIF file the final GIF file is twice the
                             size of the original.  Why is this?

                  Answer     There are two things which might cause this to
                             happen:

                             JPEG compression doesn't really work well for
                             images which have large areas which are all the
                             same colour.  The reason for this is that JPEG is
                             a lossy compression technique.  Therefore you are
                             not going to get back exactly the same values for
                             each pixel in an area that was one solid colour
                             before being JPEG compressed.  But GIF compression
                             works much better on areas which are one solid
                             colour, so, when you GIF compress these areas,
                             they are quite a bit larger than they were before.
                             The solution to this problem is to use HSI JPEG
                             compression, which automatically detects large
                             areas of solid colours and does not JPEG compress
                             them.  The problem with HSI JPEG compression is
                             that it isn't compatible with JPEG or JFIF.


                             The other possibility is that the input GIF file
                             didn't have very many different colours.  When you
                             converted it to a JPEG file the number of colours
                             in the file was lost (JPEG gray-scale files always
                             use 256 shades, and JPEG colour files are always
                             true colour).  When the JPEG file was converted
                             back to a GIF file Alchemy assumed you wanted 256
                             colours in the file, and a 256 colour GIF file is
                             bigger than a 16 colour GIF file.  To prevent this
                             you can use a -c32 (or however many colours the
                             original had) option in the command line; this
                             forces Image Alchemy to use that many colours for
                             the output file.


                Question     I keep getting "Out of Memory trying to ..."
                             messages.  Help!

                  Answer     Image Alchemy is running out of memory.  If you
                             are running on an IBM PC you can use alch386
                             instead of alchemy to do the conversion (if you
                             were running alch386 when you received this error
                             please contact us).

                             If you are running one of the UNIX versions of
                             Alchemy this message indicates that you are
                             running out of swap space.  Contact your system
                             administrator to find out how you can increase the
                             size of your swap space.



                   Copyright (c) 1990-1994 Handmade Software, Inc.          187 


                Question     I am using Alchemy to display a 320x400 IFF image
                             created by an Amiga.  When I use just the -v
                             option the image comes out tall and skinny.  When
                             I use the -V option, which is supposed to correct
                             the aspect ratio, things get worse instead of
                             better (the image is even skinnier).  What's going
                             on?

                  Answer     As near as we can tell, some Amiga software has a
                             different idea of what aspect ratio is than the
                             rest of the world.


                             For displays, aspect ratio is defined as the ratio
                             of the width of a single pixel to the height of a
                             single pixel.  So if you have square pixels (which
                             you do on a standard monitor in 640x480 mode) the
                             aspect ratio is 1 to 1 (commonly written as 1:1).
                             When you change display modes the height and width
                             of the total display area does not change; what is
                             changing is the width and height of each pixel,
                             which means that the aspect ratio changes.  For
                             example, a 640x400 display has an aspect ratio of
                             1:1.2 (that means each pixel is 1.2 times as tall
                             as it is wide (which makes sense since 480/400
                             equals 1.2)).  A 640x200 display has an aspect
                             ratio of 1:2.4.


                             Now this is where it gets interesting in terms of
                             IFF files.  The aspect ratio number stored in
                             Amiga IFF files for 320x400 images is 1:1.1,
                             meaning pixels are 1.1 times as tall as they are
                             wide, so therefore the actual image should be the
                             equivalent size of a 320x440 image with square
                             pixels.  And this is what Alchemy will attempt to
                             display when you use the -V option (Alchemy never
                             makes any dimension larger, so the actual image
                             Alchemy displays is 291x400, which is the same
                             ratio as 320x440).  However this is obviously
                             wrong, as you can tell when you examine an image.
                             As near as we can tell the correct aspect ratio of
                             these images is 5:3 (the math we used to come up
                             with this number is 640/320:480/400).  And if you
                             tell Alchemy to override the aspect ratio by using
                             a -D 167 option (167 because 5/3*100 is 166.6666)
                             the image displays correctly.  Why Amigas create
                             images which claim they are 1:1.1 remains a
                             mystery.






       188         Copyright (c) 1990-1994 Handmade Software, Inc. 

                Question     I told Alchemy to convert a PCX file to an 8 bit
                             GIF file (using the -8 option).  Yet when I get
                             statistics on the file (using -x) Alchemy reports
                             the file only has 16 colours.

                  Answer     Alchemy will always store the file using the
                             smallest bits-per-pixel allowable for the given
                             image (this results in the smallest possible
                             file).  In this case the input file only had 16
                             colours in it.


                             Things get more unpredictable with formats such as
                             Sun Raster (which requires 1 bit files to be black
                             and white) and SGI (which requires 8 bit files to
                             be gray-scale).  In these cases Alchemy will
                             always do the best it can (giving you a warning
                             message if it does something which may surprise
                             you later).


                Question     I've converted a Mac PICT file to a GIF file, but
                             the GIF file is missing some or all of the
                             information that was in the PICT file.  What
                             happened to it?

                  Answer     PICT files are a combination of drawing commands
                             (such as lines, rectangles, and circles) and
                             raster areas (called pixMaps).  Alchemy can only
                             read the raster portions of the files.  Programs
                             such as MacDraw and MacDraft write out files with
                             drawing commands, programs such as MacPaint write
                             out files which are entirely raster areas
                             (pixMaps), and some programs, such as SuperPaint
                             can write out files which are either, or a
                             combination of both.  If you are using such a
                             program check the documentation on how to write
                             out files in "paint" mode.


















                   Copyright (c) 1990-1994 Handmade Software, Inc.          189 

                Question     Why can't Image Alchemy read in JPEG files
                             produced by Kodak's ColorSqueeze (or Sun's
                             VFCtool)?

                  Answer     The JPEG standard is still in draft form.  Until
                             it is a mature standard, various manufacturers
                             will implement different versions of it.  As of
                             March 1, 1991 Image Alchemy supports the JFIF
                             format and should work with any other JPEG
                             software which also claims JFIF compatibility.  If
                             other software you are using claims to support the
                             JFIF format and you are having trouble, please
                             contact us.  If the other software does not
                             support JFIF, contact the manufacturer and tell
                             them they should send you an update which does
                             (you can tell them to contact us if they need a
                             copy of the JFIF standard).


                Question     When I convert a 32 bit Targa file to a GIF file
                             and then to a JPEG file it doesn't look nearly as
                             good as if I convert the Targa File directly to
                             the JPEG file.  What can I do to maintain high
                             quality in JPEG compressed files?

                  Answer     When the Targa file was converted to the GIF file
                             Image Alchemy had to reduce the number of colours
                             in the file (the original Targa File had up to 16
                             million colours, GIF files are limited to 256
                             colours).  This step is known as colour
                             quantization (Image Alchemy uses the Heckbert
                             Median Cut method for quantization; see Appendix
                             B, Colour and Dithering, for more information).
                             The difficulty with colour quantization is that it
                             leaves artifacts known as colour banding.  To
                             reduce this phenomenon Image Alchemy dithers the
                             image (you can see the effect of colour banding by
                             turning off dithering by using the -d0 option).
                             Unfortunately a dithered image does not JPEG
                             compress very well (dithering adds a lot of high-
                             frequency information to an image; JPEG
                             compression attempts to remove much of that
                             information).  In addition JPEG images are always
                             continuous colour images, so when the JPEG file is
                             decompressed it has to be colour quantized and
                             dithered again.  Dithering a previously dithered
                             image reduces the quality even more.  The solution
                             is to use the best starting quality you can for
                             JPEG compression, ideally a continuous tone image.
                             The compressed image size will be smaller than if
                             you had started with a paletted image and the
                             quality will be better.




       190         Copyright (c) 1990-1994 Handmade Software, Inc. 

                Question     I've converted an HP PCL file to a GIF file, but
                             the GIF file is missing some or all of the
                             information that was in the PCL file.  What
                             happened to it?

                  Answer     PCL files have the same problem as PICT files (see
                             above); they are a combination of drawing commands
                             (such as lines and rectangles) and raster areas
                             (called rasters) and Alchemy can only convert the
                             raster areas in PCL files.  PCL Files also contain
                             font and text information, which is also lost.
                             Unfortunately there isn't any general way to
                             preserve this data with Alchemy.


                             One thing which you can do if running Microsoft
                             Windows 3.0 is to install Adobe Type Manager
                             (ATM).  ATM automatically intercepts any text
                             commands and converts them to rasters.  In
                             addition, the standard Windows 3.0 HP PCL driver
                             only generates rasters, not vectors.  So the file
                             will appear in its entirety when converted by
                             Alchemy.  Contact us if you want further
                             information on using Alchemy with Windows.


                Question     I converted a PCX file with 16 colours to a 16
                             shades of gray TIFF file using the -b and -t
                             options.  The 16 colour PCX file had some shades
                             of gray in it which were changed in the TIFF file.
                             How can I prevent this?

                  Answer     The problem is that gray-scale TIFF files have a
                             uniformly spaced gray palette.  If you create a
                             TIFF file with 16 shades of gray it will have the
                             following shades in it:  0, 17, 34, 51, 68, 85,
                             102, 119, 136, 153, 170, 187, 204, 221, 238, and
                             255.  However the 16 colour PCX file you started
                             with probably didn't have those exact colours in
                             it (for example, PCX files written out by
                             Windows 3.0 Paint have shades of gray which
                             correspond to 0, 128, 192, and 255).  So Alchemy
                             did the best it could and matched the input
                             colours to the output colours (and depending on
                             the other options that you specified may also have
                             dithered the image).










                   Copyright (c) 1990-1994 Handmade Software, Inc.          191 

                             The solution is to tell Alchemy to write out a 256
                             colour gray-scale TIFF file (which you do by
                             adding a -c256 to the -b and -t options).  This
                             file still has a uniform gray palette; but that
                             palette now contains every colour:  0, 1, 2, 3,
                             ..., 255.  Therefore Alchemy can map, for example,
                             the colours 128 and 192 to their exact match.
                             This does have the disadvantage of making the
                             resulting 256 colour TIFF file twice as large as
                             the 16 colour TIFF file, but this is the only way
                             to guarantee that Alchemy can find an exact match
                             for all the shades of gray in the input file.


                Question     How do I get a copy of the current draft JPEG
                             standard?

                  Answer     The JPEG standard is an ISO/IEC standard currently
                             in Committee Draft form.

                             Contact your local ISO/IEC office to get a copy.
                             The reference numbers are ISO/IEC JTC 1 and /SC 2
                             N2215; the document number is ISO/IEC CD 10918-1.

                             In the United States you can contact ANSI at:
                                ANSI
                                11 West 42nd St.
                                New York, NY  10036
                                (212) 642-4900


                Question     Do you give multiple copy discounts?  Do you have
                             site licenses?  Are you interested in licensing
                             the source code?

                  Answer     Yes.  Yes.  Yes.  Contact us for more information.




















       192         Copyright (c) 1990-1994 Handmade Software, Inc. 

                                                                              B



       Colour and Dithering
       ------------------------------------------------------------------------


       Paletted vs.          Colour images are normally stored in one of two
       true colour           ways:  as an array of direct colour values
                             (usually red, green, and blue) (referred to as a
                             true colour file in this document) or as an array
                             of indices into a colour-map which contains red,
                             green, and blue colour values (referred to as a
                             paletted file in this document).


                             Paletted images exist because they take less
                             memory, so the hardware to display them is less
                             expensive.  The dominance of paletted hardware is
                             changing as the price of memory and the processing
                             power it takes to update large amounts of memory
                             at a reasonable speed drops (a Targa 32 board is
                             an example of a true colour board, a standard VGA
                             board is an example of a paletted board).


                             Until true colour graphics devices become the
                             norm, there is a need to convert images from true
                             colour to paletted.  This conversion is done in
                             two steps:  the first is to generate a palette for
                             use by the image;  the second is to map the image
                             to the new palette.

       Colour cube           The colour model generally used by computers is a
                             cube with red, green, and blue as the axes (this
                             is known as a colour cube or RGB cube).  Each
                             point inside the cube is a different colour,
                             depending on the amount of red, green, and blue
                             used.  In nature each of the three axes is nearly
                             continuous, therefore there are a nearly infinite
                             number of colours available.  Computer hardware
                             and software represent colours in a discrete
                             fashion.


                             For true colour displays or file formats the
                             number of discrete positions along each axis of
                             the colour cube gives the colour resolution of the
                             output device.  For example, a Targa 24 board for
                             an IBM PC has 8 bits per red, green, and blue
                             channel for a total of 24 bits (or 256 discrete
                             shades of each colour, for a total of 16 million
                             colours (256x256x256)).  This is also the colour
                             resolution of most true colour file formats.

                   Copyright (c) 1990-1994 Handmade Software, Inc.          193 


                             A 15 bit SVGA boards has 5 bits per channel, for a
                             total of 32x32x32 different colours (32,768).
                             This is the same colour resolution as a Targa 15
                             file.


                             A paletted display or image file has the same
                             colour resolution limit as a true colour display
                             or image file, but in addition there is a limit on
                             how many points inside the cube can be used at the
                             same time.  An 8 bit file format, such as GIF,
                             allows 256 different colours out of 16 million.  A
                             non-true-colour SVGA board also only allows 256
                             different colours at one time.


                             So, converting a true colour file to a paletted
                             file involves reducing the number of occupied
                             points in the colour cube.  There are several ways
                             this can be done.


       Generating a          Image Alchemy supports two methods of generating a
       palette               palette:



        Uniform palettes     The simplest and fastest method is to use a
                             palette containing colours which are uniformly
                             distributed in the RGB cube, this is referred to
                             as a uniform palette.  This has the advantage that
                             it's fast and the same palette can be used for any
                             image; the primary disadvantage is that most
                             images don't contain colours from everywhere in
                             the RGB cube, so palette entries are wasted
                             representing colours that aren't needed for the
                             particular image being converted.


















       194         Copyright (c) 1990-1994 Handmade Software, Inc. 

        Optimal palettes     To generate a palette which is better for
                             representing a particular image, Image Alchemy
                             supports Heckbert's median cut algorithm.  This
                             algorithm first builds a three dimensional table
                             (a histogram cube) indicating how popular any
                             given colour in the RGB cube is in the image being
                             converted.  It then proceeds to subdivide this
                             histogram cube (by dividing boxes in half) until
                             it has created as many boxes as there are palette
                             entries.  The decision as to where to divide a box
                             is based on the distribution of colours within the
                             box.  This algorithm attempts to create boxes
                             which have approximately equal popularity in the
                             image.  Palette entries are then assigned to
                             represent each box.

                             There are other methods of generating a palette
                             from an image, but Heckbert's algorithm is
                             generally regarded as the best tradeoff between
                             speed and quality.

           Modifying the     You can change the method used to select a colour
       palette selection     to represent each box by use of the -z options.
                 process

                             The default method is to use the mean of all the
                             colours in the box.  However for some images
                             slightly better results can be obtained by using
                             the center of the box (without regard to where the
                             pixels are in the box).


                             For images being reduced to a very small number of
                             colours (less than 16) better results can be
                             obtained by using a corner of the box (the boxes
                             tend to be large when reducing an image to a small
                             number of colours; therefore picking colours near
                             the centers of the boxes will give you muddy
                             colours, while using corners of the boxes will
                             give you saturated colours).  And having saturated
                             colours allows the dithering algorithms to
                             generate better looking images.

       Mapping the image     The next step is to map the image to the new
       to the palette        palette; this is where dithering becomes
                             important.



            No dithering     The simplest approach is to map every colour in
                             the original image to the palette entry which is
                             closest to it (this is what Image Alchemy does if
                             you specify no dithering).



                   Copyright (c) 1990-1994 Handmade Software, Inc.          195 

                             However, since the palette entries generally
                             represent several different colours in the
                             original image, this results in colour banding
                             where areas of smooth colour changes in the
                             original become areas of one solid colour in the
                             paletted version.

           Advantages of     This can be alleviated by dithering the image data
               dithering     such that any given pixel might not be mapped to
                             its closest palette entry, but the average over
                             some area of the image will be closer to the
                             correct colour than it would otherwise be.  Image
                             Alchemy uses a class of algorithms called "error-
                             diffusion" to do dithering.

         Error diffusion     These algorithms work by using the closest palette
               dithering     entry to a colour and then distributing the error
                             (the difference between the desired colour and the
                             chosen palette entry) to the nearby pixels.  This
                             process is repeated for every pixel in the image,
                             using the colour values which have been modified
                             due to the error from previous pixels.  The
                             different dithering algorithms spread the error
                             over a different area or use a different weighting
                             within the same area.

       Serpentine raster     Error diffusion can be done as a normal raster
                             (left to right, top to bottom) or as a serpentine
                             raster (alternating left to right and right to
                             left, top to bottom).  A serpentine raster tends
                             to break up visible patterns introduced by
                             dithering.

                   Noise     Random noise can also be added to help break up
                             visible patterns in the resulting image.


       Further               For more information on Heckbert's median cut and
       information           dithering see the appropriate reference listed in
                             the References section below.
















       196         Copyright (c) 1990-1994 Handmade Software, Inc. 

                                                                              C



       What is JPEG Compression?
       ------------------------------------------------------------------------


       Who are those         JPEG stands for the "Joint Photographic Experts
       JPEG guys?            Group".  This is a group of experts who defined a
                             standard compression scheme for still images,
                             commonly called JPEG Compression.  Currently the
                             standard is still in draft form.

       Overview              JPEG Compression consists of a series of complex
                             mathematical operations, including: colour space
                             conversion, discrete cosine transforms,
                             quantization, and entropy coding.  After these
                             steps you end up with an image which takes fewer
                             bits to store than you started out with.

                             However, when you decompress a JPEG compressed
                             image you end up with an image that is not quite
                             the same as the original  (which is why JPEG
                             Compression is referred to as "lossy").

       Is lossy              You might well ask why anyone would want to
       compression bad?      compress an image using a lossy technique.
                             Compression ratios for lossy compression are much
                             better than for lossless compression and the loss
                             is generally very small.  And, in fact, every
                             operation of converting an image is lossy (the
                             original photographic or electronic process which
                             captured the image was lossy, scanning or
                             digitizing the image was lossy, displaying the
                             image on a monitor is lossy, and printing the
                             image is lossy).


       Details               JPEG compression involves the following steps:

                  Step 1     The image is converted to a colour space with
                             separate luminance and chrominance channels.  This
                             is done because the human eye is far more
                             sensitive to the luminance information (Y) than it
                             is to the chrominance information (Cb and Cr); by
                             separating them, it's possible to compress the
                             chrominance information more than the luminance
                             before the perceived image quality suffers.







                   Copyright (c) 1990-1994 Handmade Software, Inc.          197 

                             This step isn't specified in the JPEG draft (it
                             doesn't discuss colour space at all), but is
                             standard practice.  Image Alchemy uses CCIR-601
                             YCbCr, which is the colour space specified by the
                             JFIF standard.

                  Step 2     The luminance and chrominance information are
                             separately transformed to the frequency domain
                             using a discrete cosine transform acting on 8x8
                             pixel blocks.


                             To reduce the amount of data which needs to be
                             compressed the chrominance information may be sub-
                             sampled first.  Alchemy uses 2h:1v:1h:1v:1h:1v
                             sub-sampling when writing JPEG files, which means
                             that the first component (luminance) has twice as
                             many samples horizontally as the other two
                             components (chrominance), and the same number of
                             samples vertically.  Alchemy can read JPEG files
                             with any sub-sampling allowed by the draft
                             standard.

                  Step 3     The transformed data is quantized (so some
                             information is thrown away).  The samples
                             representing higher frequencies are generally
                             quantized using larger steps than those
                             representing low frequencies.


                             The quality level you specify is used to scale a
                             set of quantization values which have been found
                             to cause the quantized data to all have
                             approximately equal importance visually.  A lower
                             quality number will cause larger quantization
                             steps to be used, and hence increase the
                             compression ratio and decrease the image quality.

                  Step 4     The quantized data is compressed using an entropy
                             coder.  Huffman and Arithmetic coding are allowed
                             by the draft JPEG standard; only Huffman coding is
                             allowed by the JFIF standard.  Huffman coding can
                             either be done with a set of fixed tables or
                             custom tables can be generated for an image.
                             Alchemy, by default, uses a fixed set of tables,
                             but can also generate custom tables which usually
                             produce 5-20% (depending on the image and quality
                             setting) better compression.  However, producing
                             custom tables requires an additional pass over the
                             image data and therefore takes a little longer.






       198         Copyright (c) 1990-1994 Handmade Software, Inc. 

       JPEG Interchange      This data corresponds to the JPEG Interchange
       Format                Format and is ready to be stored in a file.
                             Unfortunately the JPEG Interchange Format does not
                             include enough information to actually be able to
                             convert the file back to an image.  Specifically
                             the colour space used and the aspect ratio or
                             resolution of the image are not included.  Until
                             recently there was no standard way of putting this
                             information in a JPEG file.

       JFIF                  On March 1, 1991 representatives of several JPEG
                             hardware and software developers (including C-
                             Cube, Radius, NeXT, Storm Tech., the PD JPEG
                             group, Sun, and Handmade Software) met at C-Cube
                             and established the JPEG File Interchange Format
                             (JFIF).  JFIF allows for the standardization of
                             those pieces of information missing from the JPEG
                             Interchange Format and therefore allows various
                             software packages, by different vendors, to
                             produce compatible JPEG files.  If you would like
                             more information on the JFIF standard please
                             contact us.


































                   Copyright (c) 1990-1994 Handmade Software, Inc.          199 

























































       200         Copyright (c) 1990-1994 Handmade Software, Inc. 

                                                                              D



       Customer Support
       ------------------------------------------------------------------------


       Why might Alchemy     We have made every effort to insure that Image
       mess up?              Alchemy can read all files in its supported
                             formats.  However, because of poorly written
                             standards and non-adherence to standards there are
                             undoubtedly certain files that Image Alchemy does
                             not read correctly.

       What we need to       If you come across any files which Image Alchemy
       help you              has trouble with, please contact us with as much
                             of the following information as you have: version
                             of Image Alchemy you are using, type of file, type
                             of computer which generated it, name and version
                             of software which wrote the file, size of image,
                             and the number of colours in image.  We may ask
                             you to send us the file so that we can figure out
                             what went wrong.  If you send us a file we will
                             attempt to modify Image Alchemy so that it can
                             read the file.  Once Alchemy is modified, we will
                             send you an updated copy of it.

                             Similarly, if any files that Image Alchemy writes
                             cannot be read by other software please contact
                             us.  We may ask you to send us a copy of a file
                             that can be read by that software package for
                             comparison.

                             Please contact us even if you are just using a
                             demo copy of Alchemy.  In addition to helping fix
                             a bug, we feel the best way to get you to purchase
                             a copy of Alchemy is to demonstrate how committed
                             we are to customer support.

















                   Copyright (c) 1990-1994 Handmade Software, Inc.          201 

       How to contact us     Our address and phone numbers are:

                                Handmade Software, Inc.
                                48820 Kato Road, Suite 110
                                Fremont, CA  94538
                                
                                800 358 3588 (Toll-free from within the U.S.)
                                +1 510 252 0101 (Voice)
                                +1 510 252 0909 (Fax)

                             The most efficient way to contact us is by e-mail;
                             this is especially true if you can send us a
                             sample file which demonstrates the problem you are
                             having.  Please enclose a short note with your
                             name and phone number so that we may call you if
                             we need further information.  Our e-mail addresses
                             are:

                                Internet:  hsi@netcom.COM
                                CompuServe:  71330, 3136

                             We also have a 24 hour bulletin board where you
                             can upload and download files.  It speaks 2400
                             baud, 9600 baud (v32, v42, and v42.bis), and PEP;
                             its number is:

                                +1 510 252 0929 (BBS)

                             If you upload a file to our BBS please leave a
                             short note to the SYSOP so that we know what the
                             problem you are having is.

                             We also have a fax-on-demand system which allows
                             you to request and automatically receive faxes
                             from your fax machine. Its phone number is:

                                +1 510 252 0303 (fax-on-demand)



















       202         Copyright (c) 1990-1994 Handmade Software, Inc. 

                                                                              E



       Binary Information Files (BIF)
       ------------------------------------------------------------------------


       Overview              Binary files are image files which are just data.
                             In other words, they do not contain any
                             information other than the actual pixels in the
                             image file.  In order to read these files you must
                             create a file using a text editor which describes
                             to Alchemy the format of the file you are trying
                             to read in.  This is called a BIF file (and
                             typically has the extension .bif).

       Required              At the minimum a BIF file needs to contain the
       information           filename of the image data file and either the
                             height or the width of the image.  Alchemy will
                             make assumptions about the other characteristics
                             of the image based on the information that it is
                             given and the total length of the image file.


       BIF file format       The first line contains the letters BIF, which
                             identifies the file as a BIF file.

                             Each of the rest of the lines in the BIF file
                             consist of an information tag followed by the
                             information.  The spelling of the tags must be
                             exact or Alchemy will report an unknown tag error.
























                   Copyright (c) 1990-1994 Handmade Software, Inc.          203 

       Tags

                     Tag     Description

                filename     The name of the file containing the binary data.

                   width     The width of the image data, in pixels.

                  height     The height of the image data, in pixels.

                  planes     The number of planes of image data (1, 2, 3, or
                             4).
                             A 1 plane image is assumed to be gray-scale, a 2
                             plane image is a gray-scale image with an alpha
                             channel, a 3 plane image is an RGB image, and a 4
                             plane image is an RGB image with an alpha channel.

                  header     The size of the header, in bytes.  This many bytes
                             are skipped when reading the file.

             leftpadding     The number of bytes to remove from the beginning
                             of each scan line.

            rightpadding     The number of bytes to remove from the end of each
                             scan line.

                   order     The order of the pixels.
                             For 2 channels either ga or ag(g=gray, a=alpha).
                             For 3 channel images, this can be any sequence of
                             r, g, and b:  rgb, rbg, grb, gbr, brg, or bgr
                             (r=red, g=green, b=blue).
                             For 4 channel images, this can be any sequence of
                             a, r, g, and b (a=alpha).

                             The defaults are g, ga, rgb, and rgba, depending
                             on the number of planes.

              interleave     The type of interleaving of the pixel data:
                             0:  No interleave RGBRGBRGBRGBRGBRGB...
                             1:  Line interleave    RRR...GGG...BBB...RRR...GGG
                             ...BBB...
                             2:  Plane interleave   RRRRRR...GGGGGG...BBBBBB...

                             The default is 0, no interleave.

              upsidedown     The presence of this tag indicates that the data
                             in the file is recorded from the bottom of the
                             screen up to the top of the screen.



       Comments              Lines beginning with a # are treated as comments.
                             Comments and blank lines are ignored when
                             processing the BIF file.


       204         Copyright (c) 1990-1994 Handmade Software, Inc. 

       Palette files         If the binary file has a palette available, you
                             can use that palette by writing your own software
                             to convert it to a .PAL file and using the -F
                             option while reading the BIF file.

       Example               This is an example BIF file which can be used to
                             read a 640 pixel wide, true colour HSI Raw file.
                             Note that HSI raw files have a 32 byte header
                             which is being skipped.  Of course you could read
                             the Raw file directly using Alchemy, but this is
                             after all an example of a BIF file.

                             BIF
                             width    640
                             #skip past header
                             header    32

                             filename  sample.raw
                             planes     3

                             #the tags below aren't actually needed,
                             #since rgb and non-interleave are
                             #the default, but they are included
                             #here to give an example of what those
                             #tags looks like

                             order   rgb

                             interleave    0

       Using the example     Assuming the BIF file is called sample.bif, the
       BIF file              following Alchemy command can be used to convert
                             the image to a GIF file:

                                alchemy sample.bif -g

                             The height of the image will be automatically
                             calculated from the length of the file and the
                             width, header, and planes tags.

                             A BIF file is treated as an ordinary file, so all
                             the standard Alchemy commands may be used with it.














                   Copyright (c) 1990-1994 Handmade Software, Inc.          205 

























































       206         Copyright (c) 1990-1994 Handmade Software, Inc. 

                                                                              F



       HSI Raw Files
       ------------------------------------------------------------------------


       History               The HSI Raw format was originally an internal
                             format to Image Alchemy.  Because of user demand
                             the format has been documented to allow others to
                             read and write HSI Raw files.

       Overview              HSI Raw files are completely uncompressed,
                             unpacked, and unpadded image data files.
                             Therefore they tend to be larger than almost any
                             compressed file format.  However, they have the
                             advantage, as far as Alchemy is concerned, that
                             they are very fast to read and write and the
                             location of any pixel in the image may be found by
                             simple calculations.

                             If you need to convert custom files to a format
                             that Alchemy can read we recommend using a Raw
                             file; it is the simplest format to write and the
                             fastest for Alchemy to read.

       Variations            There are two types of HSI Raw Files:  paletted
                             and true colour.  Paletted images are stored one
                             byte per pixel with a palette at the beginning of
                             the file.  True colour files are stored three
                             bytes per pixel.

              Gray-scale     Gray scale files are stored as paletted files with
                             a palette that contains all gray values.  Alchemy
                             automatically recognizes such files during reading
                             and will treat them appropriately.

         Black and white     Black and White files are stored as paletted files
                             with a palette that contains two values, black and
                             white.  Alchemy automatically recognizes such
                             files during reading and will treat them
                             appropriately.

       Warning               Note that Handmade Software, Inc. reserves the
                             right to make changes to this format at any time
                             and without notice.  And while it is unlikely, it
                             is possible that future versions of Image Alchemy
                             will not support this format.







                   Copyright (c) 1990-1994 Handmade Software, Inc.          207 

       Old version files     This appendix describes version 4 Raw files.  This
                             is the version that Image Alchemy has written
                             since March 1991.  Before this Alchemy wrote
                             version 2 and 3 raw files (version 2 were 8 bit
                             files, version 3 were 24 bit files).  Those raw
                             files can be read by current versions of Image
                             Alchemy but are not otherwise supported.  If you
                             run across any of these raw files the easiest
                             thing to do is to use a current copy of Alchemy to
                             convert them to a version 4 raw file.

       Details

               Word size     All values which are not otherwise identified are
                             two byte integers (16 bits).  This is the native
                             integer size of most IBM PC C-compilers but not
                             Macintosh and UNIX C-compilers.


              Byte order     All integers are stored high byte first (big-
                             endian order).  This is the native mode for
                             Macintosh's and Sun's but not the native mode for
                             IBM PC's.


                             See below for a CPU independent method to read and
                             write 2-byte integers.

            Pixel format     Paletted files are stored one byte per pixel.

                             True colour files are stored as three bytes per
                             pixel in red, green, blue order.

                 Padding     Neither the palette information nor the pixel data
                             is padded to anything other than a byte boundary.
                             This means that if you store a file which is 13 by
                             11 pixels it will occupy 429 bytes if stored as a
                             true colour file (not including the header), or
                             143 bytes if stored as a paletted file (not
                             including the header and palette data).

                     Hex     Numbers including a 0x prefix are hex; all other
                             numbers are decimal.



       File format           The header for a paletted file is 32 bytes plus
                             the size of the palette.  The header for a true
                             colour file is exactly 32 bytes (a true colour
                             file contains no palette).

            Magic number     Six bytes used to identify the file as an HSI Raw
                             file:

                                0x6d 0x68 0x77 0x61 0x6e 0x68

       208         Copyright (c) 1990-1994 Handmade Software, Inc. 

                 Version     An integer used to identify the version HSI file:

                                0x0004

                   Width     An integer indicating the width of the image (in
                             pixels).

                  Height     An integer indicating the height of the image (in
                             pixels).

            Palette size     An integer indicating the number of entries in the
                             palette.  Range is 2 to 256.  A 0 or -24 indicates
                             a true colour image (which has no palette data).

          Horizontal DPI     An integer indicating the horizontal resolution of
                             the image, in dots per inch.  A zero indicates
                             that the resolution is unknown.  A negative number
                             is used if only the aspect ratio is known.

            Vertical DPI     An integer indicating the vertical resolution of
                             the image, in dots per inch.  A zero indicates
                             that the resolution is unknown.  A negative number
                             is used if only the aspect ratio is known.

                   Gamma     An integer indicating the gamma of the image,
                             scaled by 100 (a gamma of 2.2 is stored as 220).
                             A zero indicates that the gamma is not known.

                Reserved     Twelve bytes reserved for future use.  Should be
                             set to zero when writing.

                 Palette     The palette data is stored as 3 bytes per palette
                             entry.  The bytes are in red, green, blue order; 0
                             is black, 0xff is full intensity.

                             True colour raw files have no palette.

              Image data     The image data.



       Example files

         8 bit paletted,     6D 68 77 61 6E 68 00 04  01 40 00 C8 01 00 00 00
              320 x 200:     00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00
                             49 24 24 24 00 00 00 00  00 DB 6D 6D FF 92 92 FF
                             B6 B6 92 49 49 FF DB DB  FF B6 92 FF FF DB FF DB
                             B6 FF FF FF B6 6D 6D 6D  24 24 DB 92 6D 6D 49 49
                             ...







                   Copyright (c) 1990-1994 Handmade Software, Inc.          209 

             24 bit true     6D 68 77 61 6E 68 00 04  01 40 00 C8 00 00 00 00
                 colour,     00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00
              320 x 200:     49 24 24 49 24 24 49 24  24 49 24 24 49 24 24 49
                             24 24 49 24 24 49 24 24  49 24 24 49 24 24 49 24
                             24 49 24 24 49 24 24 49  24 24 49 24 24 49 24 24
                             ...


       Reading a two         int getWord(int i, FILE *stream) {
       byte integer             register int temp;
                                temp=getc(stream)<<8;
                                return(getc(stream) | temp);
                             }

       Writing a two         int putWord(int i, FILE *stream) {
       byte integer             putc(i>>8, stream);
                                return(putc(i&0xff, stream));
                             }






































       210         Copyright (c) 1990-1994 Handmade Software, Inc. 

                                                                              G



       Undercolour Removal Files
       ------------------------------------------------------------------------


       Summary               Undercolour removal files are text files which
                             control the conversion from RGB to CMYK colour
                             space.


                             This conversion consists of four steps.

                             The first is to convert an RGB value to an ideal
                             CMY value; this simply involves negating the RGB
                             values.

                             The next step is to determine how much black is in
                             that colour; this is done by finding the minimum
                             of the CMY values and using that as an index into
                             the black removal portion of the Undercolour
                             Removal tables documented below.  These tables
                             have independent values for how much black to use
                             for that pixel and how much black to subtract from
                             the CMY values.

                             Next, a linear transform is optionally applied to
                             the CMY portion of the CMYK pixel.

                             Finally the CMYK values are optionally translated,
                             independently, through the CMYK density correction
                             tables (this last step is only used if the image
                             is going to be dithered output on a 1 bit per
                             pixel per component device).




















                   Copyright (c) 1990-1994 Handmade Software, Inc.          211 

       File format

           Black removal     The first 256 non-comment lines contain
                  tables     undercolour removal values corresponding to
                             computed black values of 0 (white) to 255 (black).


                             Each of these lines has two numbers; the first
                             indicates how much black to use in place of the
                             computed black value corresponding to the line,
                             and the second indicates how much black to
                             subtract from the cyan, magenta, and yellow
                             components (this value must not be greater than
                             the corresponding computed black value).


                             After the black removal block the remaining blocks
                             may appear in any order.

              CMY linear     If there is a line which says only "HSI CMY
               transform     matrix" then the next 3 non-comment lines contain
                             a matrix representing a linear transform which is
                             applied to the cyan, magenta, and yellow
                             components after black removal and before applying
                             the density map.  The entries are normalized
                             around 256.  The first row and column represent
                             cyan, the second magenta, and the third yellow.
                             The rows are multiplied by the input cyan,
                             magenta, and yellow values to create the corrected
                             values.  A matrix of

                                256   0   0
                                  0 256   0
                                  0   0 256


                             is equivalent to omitting the matrix and causes no
                             correction to take place.  In this case it would
                             be preferable to omit the matrix as the conversion
                             will run slightly faster without it.


            CMYK density     If there is a line which says only "HSI CMYK
       correction tables     density map" then the next 256 non-comment lines
                             contain density correction tables, corresponding
                             to cyan, magenta, yellow, and black values of 0
                             (white) to 255.  Each of these lines has four
                             numbers representing, in order, the amount of
                             cyan, magenta, yellow, and black to use in place
                             of the corresponding computed values.  These
                             tables are only applied during dithering; they
                             will not be used for those CMYK output formats
                             which are continuous tone, as devices which take
                             continuous tone input data should be doing their
                             own correction.

       212         Copyright (c) 1990-1994 Handmade Software, Inc. 

                Comments     Any line beginning with ';' is a comment and is
                             ignored.



       Example               The following undercolour removal file has
                             undercolour removal tables, CMYK density
                             correction tables, and a CMY colour correction
                             matrix.


                                ; Undercolour removal file
                                ;
                                  0   0
                                  1   1
                                  1   1
                                  2   2
                                  3   3
                                ... (256 entries total)
                                169 169
                                169 169
                                170 170
                                ;
                                HSI CMY matrix
                                ;the following matrix leaves the
                                ; Cyan and Yellow planes alone, and
                                ; subtracts a bit from the Magenta
                                ; plane when there's Cyan present.
                                ;
                                256   0   0
                                -32 256   0
                                  0   0 256
                                ;
                                HSI CMYK density map
                                ;
                                  0   0   0   0
                                  0   0   0   0
                                  0   0   0   0
                                ... (256 entries total)
                                248 248 248 248
                                251 251 251 251
                                253 253 253 253
                                255 255 255 255













                   Copyright (c) 1990-1994 Handmade Software, Inc.          213 

























































       214         Copyright (c) 1990-1994 Handmade Software, Inc. 

                                                                              H



       PAL Files
       ------------------------------------------------------------------------


       Overview              PAL files are text files which contain a palette
                             in an ASCII form.  Alchemy can extract palettes
                             from other file formats and write PAL files.
                             Alchemy can also use PAL files when converting
                             images.

       File format           The first line contains the letters "PAL"; this
                             identifies the file as a palette file.

                             The next line contains an integer indicating the
                             number of palette entries.  Valid values are 2
                             through 256.

                             The rest of the file consists of lines of 3
                             numbers, representing the red, green, and blue
                             values for each of the colours.  These have a
                             range of 0 (black) to 255 (full intensity).  Any
                             information after the 3 numbers is treated as a
                             comment and ignored.

       Example
                                PAL
                                8              ;# colours
                                  0   0   0    ;black
                                255   0   0    ;bright red
                                  0 128   0    ;dark green
                                255 255   0    ;yellow
                                  0   0 255    ;blue
                                255   0 255    ;magenta
                                 63  63  63    ;gray
                                255 255 255    ;white

















                   Copyright (c) 1990-1994 Handmade Software, Inc.          215 

























































       216         Copyright (c) 1990-1994 Handmade Software, Inc. 

                                                                              I



       Acknowledgments
       ------------------------------------------------------------------------


       Summary               Almost all the software which comprises Image
                             Alchemy was written in house.  However some of the
                             modules are modifications of software originally
                             written by other people or software that we've
                             licensed.

                    TIFF     Image Alchemy's TIFF I/O is based on libtiff which
                             is copyright by Sam Leffler and is used with his
                             permission.  If you are interested in reading or
                             writing TIFF files we strongly suggest that you
                             start with libtiff.

                             Libtiff is available by anonymous ftp as
                             ucbvax.berkeley.edu:pub/tiff/*.tar.Z or
                             uunet.uu.net:graphics/tiff.tar.Z.

                             If you cannot get a copy of libtiff via anonymous
                             ftp please contact us for a free copy.

         LZW Compression     The LZW compression method is the subject of
                             United States patent number 4,558,302 and
                             corresponding foreign patents owned by Unisys
                             Corporation and the use of it for TIFF LZW
                             compression is licensed from them.


                             Further information on licensing this patent can
                             be obtained from:

                             Unisys Corporation
                             Welch Licensing Department
                             Office of the General Counsel
                             M/S C1SW19
                             Blue Bell, PA  19424

             VGA display     The MS-DOS version of Image Alchemy's 640x400 SVGA
                             display routines are based on VGAKIT, written by
                             John Bridges.

                             VGAKIT is available free of charge from a variety
                             of bulletin boards

                             If you cannot find VGAKIT locally please contact
                             us for a free copy.




                   Copyright (c) 1990-1994 Handmade Software, Inc.          217 

                Spawning     The spawn function used by the MS-DOS GUI uses the
                             SPAWNO routines by Ralf Brown to maximize the
                             available memory while spawning Alchemy.

                             For more information on SPAWNO contact:

                             Ralf Brown
                             813 Copeland Way, Suite 26
                             Pittsburgh, PA  15232
                             +1 713 880 3059
                             internet:  ralf+@cs.cmu.edu













































       218         Copyright (c) 1990-1994 Handmade Software, Inc. 

                                                                              J



       Other Useful Software
       ------------------------------------------------------------------------


       Summary               There are several image processing packages
                             available for free or as shareware.

                             Please be aware that we mention these software
                             packages only as a service to Image Alchemy users.
                             We are not endorsing or recommending any
                             particular package.  Some of the packages are no
                             longer supported by their authors.

                             If you have trouble finding any of the listed
                             software please send us a blank tape or diskette
                             and we will send you a copy free of charge (please
                             be aware that the software may be quite large;
                             contact us first if you have any questions).

                             If you know of any other software which would be
                             appropriate to add to this list please let us
                             know.  If you are the author of any of these
                             packages and you would rather not be on this list
                             please let us know that also.

       IBM PC                These programs are only available as executable
                             code and can only be run under MS-DOS.

                  PicLab     A public-domain image file conversion and printing
                             tool.
                             Written by Lee Crocker and the Stone Soup Group.
                             Available via CompuServe.


                   Cshow     A shareware image viewing program.
                             Written by Bob Berry.
                             Available from:
                                Canyon State Systems and Software
                                PO Box 86
                                Sedona, AZ  86336


                   Vivid     A shareware ray-tracing program.
                             Written by Stephen B. Coy
                             Available from:
                                Stephen Coy
                                15205 NE 13th Pl., #2904
                                Bellevue, WA  98007




                   Copyright (c) 1990-1994 Handmade Software, Inc.          219 

       Workstations          These programs are only available as source code
                             and generally require a workstation running UNIX
                             or one of its variants.


             Utah Raster     Written by Spencer W. Thomas, Rod G. Bogart, and
           Toolkit (URT)     James Painter.
                             Available via anonymous FTP as pub/urt-3.0.tar.Z
                             via anonymous ftp from cs.utah.edu,
                             weedeater.math.yale.edu, or
                             freebie.engin.umich.edu.


            Fuzzy Bitmap     Written by Michael Mauldin
            Manipulation     Available by anonymous ftp as
                   (FBM)     nl.cs.cmu.edu:/usr/mlm/ftp/fbm.tar.Z,
                             uunet.uu.net:pub/fbm.tar.Z, or
                             ucsd.edu:graphics/fbm.tar.Z.


         Portable BitMap     Written by Jef Poskanzer
               (PBMPLUS)     Available by anonymous ftp as
                             expo.lcs.mit.edu:contrib/pbmplus.tar.Z or
                             ftp.ee.lbl.gov:pbmplus.tar.Z.


        Img Software Set     Written by Paul Raveling
                             Available by anonymous ftp as
                             expo.lcs.mit.edu:contrib/img_1.3.tar.Z or
                             venera.isi.edu:pub/img_1.3.tar.Z.


























       220         Copyright (c) 1990-1994 Handmade Software, Inc. 





       Glossary
       ------------------------------------------------------------------------


           Anonymous FTP     An easy way to transfer files via the Internet.
                             If you don't have Internet access you can't use
                             anonymous FTP; if you do have Internet access you
                             probably already know about it (if you don't, ask
                             your system administrator or local network guru).

         Black and white     An image which contains just two colours, black
                             and white.  Many file formats, such as TIFF and
                             Sun Raster, have special variations for black and
                             white images.  You can force Alchemy to write a
                             black and white image by specifying -b -c2 as
                             options.

               Dithering     A technique for reducing the amount of colour
                             banding in an image when converting from a large
                             number of different colours to a small number of
                             different colours.  Different dithering techniques
                             are usually named after the person or persons who
                             first invented them.  Alchemy supports Floyd-
                             Steinberg, Stucki, and JJN dithering; these are
                             further described in "Digital Halftoning", by
                             Robert Ulichney, MIT Press.

              Gray-scale     An image which contains just shades of gray.  Many
                             file formats, such as TIFF and Silicon Graphics,
                             have special variations for gray-scale images.
                             You can force Alchemy to write a gray-scale image
                             by specifying -b -8 as options.

                  Header     The portion of an image file that is not the
                             actual image data.  The data in a header generally
                             includes the image size (in pixels), the image
                             depth (in number of bits per pixel or number of
                             colours), and the palette (if the image has a
                             palette).  Some file formats include quite a bit
                             of additional data in the header, such as:  the
                             name of the image, the date and time the image was
                             created, and the latitude and longitude of the
                             image (primarily used by satellite image data).
                             The header is called the header because it usually
                             appears at the head of the file.  Some file
                             formats store information which is usually found
                             in the header in a separate file.





                   Copyright (c) 1990-1994 Handmade Software, Inc.          221 

         Heckbert colour     A technique for reducing the number of colours
            quantization     needed by an image, typically used to convert a
                             true colour image to a paletted image.  Named
                             after Paul Heckbert who originally described the
                             technique in "Color Image Quantization for Frame
                             Buffer Display", SIGGRAPH '82 Proceedings, p. 297.

            Magic Number     A number or sequence of numbers that is found at
                             or near the start of an image file so that
                             software may determine what type of format the
                             file is.  Most formats have a well defined magic
                             number; some formats do not, in which case Alchemy
                             examines various parameters in the header of the
                             file and guesses what format the image is.

                Paletted     An image which isn't true colour.  Each pixel in
                             the image is an index into a table of values
                             (typically red, green, and blue) which describe
                             the colour of that pixel.  Most paletted images
                             are limited to 8 bits of information, which allows
                             256 unique colours.  Most display adapters only
                             allow the display of paletted images (Alchemy can
                             display true colour images on those display
                             adapters by using a uniform palette).

             True colour     An image which does not contain a palette.  Each
                             pixel in the image is represented by at least
                             three values, typically red, green, and blue.
                             True colour images are generally produced by
                             scanners and digitizers and are better quality and
                             much larger than paletted images.  Most display
                             systems cannot display true colour images.
























       222         Copyright (c) 1990-1994 Handmade Software, Inc. 





       References
       ------------------------------------------------------------------------


       General Computer      Computer Graphics - Principles and Practice,
       Graphics              Second Edition
                             (Commonly referred to as Foley and van Dam)
                             J.D. Foley, A. van Dam, S.K. Feiner, and J.F.
                             Hughes
                             Addison-Wesley
                             ISBN 0-201-12110-7


                             Principles of Interactive Computer Graphics
                             (Commonly referred to as Newman and Sproull)
                             W.M. Newman and R.F. Sproull
                             McGraw-Hill
                             ISBN 0-07-046338-7


                             Algorithms for Graphics and Image Processing
                             Theo Pavlidis
                             Computer Science Press
                             ISBN 0-914894-65-X


                             Graphics Gems
                             Andrew S. Glassner
                             Academic Press
                             ISBN 0-12-286165-5


                             Graphics Gems II
                             James Arvo
                             Academic Press
                             ISBN 0-12-064480-0


                             Image Lab
                             Tim Wegner
                             Waite Group Press
                             ISBN 1-878739-11-5










                   Copyright (c) 1990-1994 Handmade Software, Inc.          223 

       Specific Topics

                  Colour     The Reproduction of Colour in Photography,
                             Printing & Television
                             R.W.G. Hunt
                             Fountain Press
                             ISBN 0 85242 356 X


               Dithering     Digital Halftoning
                             Robert Ulichney
                             MIT Press.
                             ISBN 0-262-21009-6

            File Formats     Graphics File Formats
                             David C. Kay and John R. Levine
                             Windcrest/McGraw-Hill
                             ISBN 0-8306-3060-0

                             Bit-Mapped Graphics
                             Steve Rimmer
                             Windcrest
                             ISBN 0-8306-3558-0

                             Supercharged Bit-Mapped Graphics
                             Steve Rimmer
                             Windcrest/McGraw-Hill
                             ISBN 0-8306-3788-5

                    JPEG     JPEG Still Image Compression Standard
                             William B. Pennebaker and Joan L. Mitchell
                             Van Nostrand Reinhold
                             ISBN 0-442-01272-1


           Image Scaling     Digital Image Warping
                             George Wolberg
                             IEEE Computer Society Press Monograph
                             ISBN 0-8186-8944-7


           PDF (Portable     Portable Document Format Reference Manual
        Document Format)     Adobe Systems Incorporated
                             Addison-Wesley
                             ISBN 0-201-62628-4











       224         Copyright (c) 1990-1994 Handmade Software, Inc. 

              PostScript     PostScript Language Reference Manual, Second
                             Edition
                             Adobe Systems Incorporated
                             Addison-Wesley
                             ISBN 0-201-18127-4

                             Adobe Type 1 Font Format, Version 1.1
                             Adobe Systems Incorporated
                             Addison-Wesley
                             ISBN 0-201-57044-0

         VGA Programming     Programmer's Guide to the EGA and VGA Cards,
                             Second Edition
                             Richard F. Ferraro
                             Addison-Wesley
                             ISBN 0-201-57025-4








































                   Copyright (c) 1990-1994 Handmade Software, Inc.          225 



























































       226         Copyright (c) 1990-1994 Handmade Software, Inc.


