                       Convert to .IMG
                       ======= == ====

                             by

                       Craig W. Daymon

            *************************************
            ***                               ***
            ***   This program is ShareWare   ***
            ***                               ***
            *************************************
            *                                   *
            *     If you use this program,      *
            *     you are requested to register *
            *     as a legitemate user by       *
            *     sending $15 (US) to:          *
            *                                   *
            *     Craig W. Daymon               *
            *     33 Chestnut Valley Drive      *
            *     Doylestown, PA                *
            *     18901 - 2216                  *
            *     USA                           *
            *                                   *
            *************************************


            Copyright 1989, 1990 - Craig W. Daymon

          *This file last updated on:

            *************************************
            *                                   *
            *          March 22, 1990           *
            *                                   *
            *************************************

*************************************************************************

   THIS IS VERSION 1.10 - PLEASE DISTRIBUTE THIS TEXT WITH THE PROGRAM

*************************************************************************

PROGRAM OPERATION:
======= =========

General:
-------

    The program will save IMG files in an uncompressed format.  This
    means that some compressed IMG files can grow significantly in
    size after conversion.  The program WILL check available disk
    space before saving ANY file.  The IMG files should be compatible
    with any programs that are able to use IMG files.  They have been
    tested with the IMG viewer from Migraph, IMG Quick View, WordUp,
    PageStream and Easy-Draw as well as a program I wrote to use the
    GEM function, v_bit_image(), to print IMG files with the help of
    GDOS. (Or 'G+Plus' from CodeHead Software.)

    The program will work in any of the standard ST resolutions, although
    a monochrome system is the ideal configuration.  I do not have access
    to a large-screen display, but the program should work on large-screens
    as well.

    Monochrome users will be able to view the conversion process for
    color images.

File Type Buttons:
---- ---- -------

    The 'File Type Buttons' are labeled with the extension of the file
    type expected when chosen.  The selection of a file type should be
    done AFTER all desired options are selected.  Following the selection
    of a file type, the File Selector will appear.  Unless the PATH
    designator is changed, only the files with the appropriate extension
    will be shown.  Choosing a file will begin the conversion.
    There is NO checking in the program to insure that the correct file
    type has been selected, so DON'T choose a file with the wrong
    extension.

    [*.NEO] - Neochrome
    [*.PI?] - DEGAS Uncompressed
    [*.PC?] - DEGAS Compressed
    [*.TN?] - Tiny
    [*.ART] - Art Director
    [*.DOO] - Doodle  (Public Painter will save in this format.)
    [*.SPU] - Spectrum Uncompressed
    [*.SPC] - Spectrum Compressed
    [*.MAC] - Mac Paint
    [*.IMG] - IMG (GEM Bit-images) *Monochrome images assumed.

    Following the execution of all the selected options, the user will
    again be presented with the file selector to save the converted
    image.

    Selection of [CANCEL] at ANY TIME from within the file selector will
    return the user to the main dialog.

OPTIONS:
-------

    [Save as *.PI3] - Selecting this option will allow the converted image
                      to be saved as a DEGAS hi-res, uncompressed file.
                      This is to allow editing with the many ST paint
                      programs that support this format.  Testing shows
                      that a converted image saved as DEGAS hi-res will
                      convert very well to medium-res DEGAS with PicSwitch.
                      For color systems, this is the best approach to
                      additional editing.  The medium-res file can then be
                      converted to IMG using 'Convert to IMG' with minimal
                      loss of quality.

                      Mac Paint and IMG files, as well as Rotation and
                      Clipping, ARE NOT available when this option is
                      selected.  And visa-versa.

    [Clip Image]    - Selecting this option will open a window, following
                      the image conversion and prior to Rotation, where
                      the user can select a portion of the converted image
                      to be saved.  The Clipping Window is explained below.

    [ROTATE]        - There are 4 buttons with Arrows that designate the
                      direction that an image will be rotated if they are
                      selected.  The default is the UP arrow.  Rotation
                      is the last option executed by the program before
                      allowing the user to save the image.  Depending on
                      the size and dimensions of the image, rotation times
                      will vary.

    [Manual Maker]  - Selecting this button will add 270 degrees to the
                      rotation of the converted image.  A 270 degree
                      rotation will be necessary to properly align a
                      graphic image in future versions of Manual Maker.
                      Think of the [Manual Maker] option as an extension
                      of Rotation.

                      (This is the main reason this program was written.)

    [Info]          - Displays a dialog explaining that the program is
                      ShareWare and giving information on where to send
                      donation/questions.

    [Hold]          - *Only available on monochrome systems.  This will
                      hold the converted image on the screen until the
                      left button is pressed and released.  Some users
                      of previous versions of this program requested this
                      option to allow monochrome users to view color
                      images.  (Particularily Spectrum.)

                      Not available for Mac and IMG formats.  Use the
                      clipping window to view those file formats.

    [Exit]          - There is NO confirmation made on exit, the program
                      will simply exit.  Pressing RETURN or ENTER will
                      also cause the program to exit from the main dialog.

Clipping Window:
-------- ------

    The clipping window uses custom cursor forms to indicate which corner
    of the clip is being selected.  If the cursor leaves the visible
    portion of the image, the cursor will resume the form of the Arrow.

    There are 2 custom forms.  The first that the user will see is the
    cursor to indicate the Upper-Left corner.  This is 2 lines meeting
    at an apex in the upper-left.  The characters 'U' and 'L' appear in
    the cursor also.  The point selected when the mouse button is pressed
    will be the point under the apex.  The sides of the cursor will lie on
    the sides of the clip.

    After pressing the left mouse button, the cursor will change to indicate
    selection of the Lower-Right corner.  This is similar to the Upper-Left
    cursor, except the apex is in the lower-right and the characters in the
    cursor are 'L' and 'R'.  The cursor will change back to the Upper-Left
    form following the selection of a lower-right corner.

    Upon selection of a corner with either cursor, intersecting lines will
    be draw indicating the sides of the selected clip.  The lines will
    extend to the entire length and width of the image and the intersection
    will indicate the corners.  (Lines may be visible when the image is
    first shown because the Upper-Left will default to the upper-left of
    the image and the Lower-Right to the lower-right of the image.)

    NOTE:   The designated corners will ALWAYS represent opposite corners
            of the clip region whether or not the Lower-Right corner is in
            the lower-right.  The same is true of the Upper-Left corner.

    Keys:
    ----

    [Esc]       - The Escape key will toggle the cursor form.  If the user
                  selects a corner and decides that it was not appropriate,
                  they can toggle back to the appropriate cursor form by
                  pressing this key and then select the corner again.

    [Undo]      - Resets the corners to the upper-left and lower-right of
                  the entire image.

    [Insert]    - Resets the Lower-Right corner to that of the entire image.

    [Home]      - Resets the Upper-Left corner to that of the entire image.


    Clicking on the CLOSE window button will exit the Clipping window and
    cause the selected section to be 'clipped' and made available for
    saving as an IMG file.

Version 1.10:
======= ====

    Version 1.10 corrects a minor problem related to Mac Paint files.  It
seems the files I used in testing earlier versions were Mac Paint files
that had been moved to an IBM and had had the MacBinary header stripped
from the file.  This meant that when versions prior to 1.10 tried to read
a Mac Paint file from a Mac, it would think there was no header.  I believe
version 1.10 will correctly determine whether the file came from a Mac or
other source and will now successfully load Mac Paint files from either.
If a problem still exists or a problem appears in reading any of the other
formats, please let me know.  Thank you.

PLEASE SEND COMMENTS:
====== ==== ========

    If there is something you would like to see added to this program,
send me a message through GEnie or write to the address above.  My address
on GEnie is: C.DAYMON.  If you have any information on any paint formats
you would like to see added or detailed information on formats already
supported, please get in touch with me.  (Not all the information I have
is accurate and I have had to make an educated guess or two.)  I am
especially looking for information on TIFF, IFF, Mac (all formats including
those for the Mac II) and more information on Art Director.

    I am considering an accessory version of this program if the program
receives enough support.  Also, faster clipping window updates and possibly
some simple editing tools (particularily a WHITE fill) are being considered.

The IMG file format (a DETAILED description)
=== === ==== ====== ========================

    The first part of any .IMG file is the header.  (Sounds reasonable.)
Each item in the header is a 16-bit word.

The format is:

    Word    |   Contents
=============================================================================
     0      |   IMG version number.  ( 0x0001 works best, believe me. )
     1      |   Header length in words.  ( IMPORTANT to check when reading. )
     2      |   Number of bit planes. ( Also IMPORTANT.  1 = Monochrome. )
     3      |   Pattern length.     ( Part of data compression, usually 2. )
     4      |   Source device pixel width in microns. (25,400 microns/inch)
     5      |   Source device pixel height in microns.
     6      |   Number of pixels per scan line.
     7      |   Number of scan lines.

Notes:
=====

    1)  I use a value of 8 for the header length as do most of the
        monochrome images available.  (No extra information.)
    2)  The number of bit planes designates the number of colors available.
        1 = Monochrome (1 bit, 2 colors), 2 = Medium Res. (2 bits, 4 colors),
        4 = Low Res. (4 bits, 16 colors)
    3)  The number of bit planes is also important in that an IMG file
        saves ALL the information for the first bit plane before saving the
        information for the second and so on...
    4)  The source pixel width and height are primarily used for
        determining the aspect ratio of an image. (Personal opinion.)
        The 'work_out[]' array used by GEM returns the pixel width and
        height for a specified device from the function, v_opnwk() in
        words 3 and 4.  In the case of the screen, I don't believe these
        values are accurate for size, but they do properly indicate the
        correct aspect ratio.  The ST monochrome screen "device" will return
        the value 372 in both words 3 and 4, indicating a 1:1 aspect ratio.
        DO NOT change IMG header words 4 and 5 to be some 'printer' specific
        setting!  This is WRONG!  The GDOS printer drivers already KNOW the
        size of a printer pixel and expect these header values to tell it
        what size the pixel was on the device that CREATED the IMG file.
    5)  Atari markets a product in europe called, HyperPaint, that can
        edit and save IMG images.  It extends the header by 17 words to
        hold the current palette.  (Or so I'm told.)  Unfortunately,
        there is no predefined way to tell WHAT extra information may be
        stored in an IMG file.  It is up to the program that created the
        file and therefore, extra information is often of little use.
        Other programs using the IMG format store the palette in separate
        files.

The Bit-Map
=== === ===

    IMG files are stored a scan-line at a time using one of three methods.
A scan-line can use more than one method of compression, but the compression
cannot extend to data of the next scan-line.  (REMEMBER: All the scan lines
for bit plane 0 are stored, followed by bit plane 1 and so on.)
The 3 methods are BIT STRING, PATTERN RUN and SOLID RUN.

NOTE:
====

    The following description is written as if the file is being READ
and the program is trying to uncompress the image.

    BIT STRING:
    === ======

        This is the one I use, it's the easiest.  (It's also the least
        efficient since it incorporates NO compression.)

    Byte 0    :     0x80    -   Specifies a Bit String.
                                (A number of bytes to be read "as is".)
    Byte 1    :     0-255   -   Number of bytes in Bit String.
    Byte 2,...:             -   No more than a scan-line's worth of raw
                                data for the bit plane being saved.

    SOLID RUN:
    ===== ===

        A solid run means that ALL the bits in the block are either
    on or off.  It is specified by a single byte whose high-order bit is
    set to indicate ON or OFF.  The lower seven bits specify the number of
    bytes making up the run with all their bits set or cleared.
    Thus, up to 127 bytes can make up a block using this method.

    Example:
    -------
        Byte = 0x03 = 00000011

        Results in 3 bytes with NO bits set.

            00000000 00000000 00000000      (Resulting Bit Pattern.)

    PATTERN RUN:
    ======= ===

        A pattern run is a number of 'pattern bytes' repeated a specified
    number of times.  The number of bytes making up a pattern is specified
    in Word 3 of the Header.  (Usually 2.)

    There are 2 bytes + the "pattern bytes" in a pattern run.

    Byte 0      :   0x00    -   Specifies a pattern run.  (Mostly)
    Byte 1      :   1-255   -   Number of times to repeat the pattern.
    Byte 2,...  :           -   Pattern to be repeated.


    *REPLICATION COUNT:
     =========== =====

        A scan-lines worth of data can be repeated up to 255 times by
    preceeding any one of the 3 previous methods with a replication
    count.  A replication count consists of 4 bytes.  The Repeat Count
    should come right BEFORE any of the data for the scan-line to be
    repeated.

    Byte 0      :   0x00    -   (A sort-of large pattern run.)
    Byte 1      :   0x00    -   To avoid confusion with a pattern run.
    Byte 2      :   0xFF    -   ??? (I don't know why.)
    Byte 3      :   0-255   -   Number of times to repeat scan-line data.

Comments:
========

    The different compression techniques CAN be mixed in a single scan-line,
but cannot extend beyond a single scan-line.  This is because the scan-line
might not end on a byte boundary.  (Width not divisible by 8.)

    This information was extracted from 2 articles appearing in recent
british ST magazines.

        June 1989 Atari ST User :   Page 117
        July 1989 ST World (UK) :   Page 48

    If you are interested in the IMG format, try to get either or both
of these magazines.  The first discusses IMG relative to the program
listing in the article, but is still rather complete.  The second is
entirely oriented to describing the IMG format.

    I guess it wasn't so short after all.  Let me know any features you
would like to see added to the program.

-Craig W. Daymon


P.S.  A version of this program will be included as part of the commercial
      version of Manual Maker.

