GEMini Atari/GEMini_Atari_CD-ROM_Walnut_Creek_December_1993.iso/files/graphics/utility/mgif35b/readme

Text File | 1991-06-18 | 12.6 KB | 247 lines

mgif 3.5
--------

This is a new version of a GIF viewer for mono STs. The major change
(version 1.1 or 1.2 was the last I posted) is to add "flicker" mode
display to simulate grayscale and to add lots more image processing
functions (the flicker trick makes it possible to render color or
grayscale images suprisingly well on a mono tube). However, a few things
were removed and need to be added (like image rotation). This only works
on monochrome and is hardwired to 640x400 tubes! It is also coded to use
about 1.4 MB of memory, so it will handle up to 640x625 images. It also
means that the binary won't run on a 1 MB system. It also uses line A
(which can be easily replaced since I only use it to draw vertical/
horizontal lines which can be done directly to Physbase). At least I did
not use any undocumented stuff :-).

NOTE: this only works on GIF87a files, not the newer standard. If/when
I get that, I might modify it to do both. It will only work on the first
image of multi-GIF files as well. Actually, mgif will also do .pi1 and .pi2
files, too.

ALSO NOTE: despite what SOME people may say, I have 2 undocumented command
line switches: -help and -version. They do what you expect. I also put
this in ALL my software, even stuff I write for unix. I think this is
INFINITELY better than using man(1) just for a quick reminder. It also
tends to be more current, especially if manpages are not updated as often
as you would like. And I think this is better than using something like
strings `which mgif` | grep -i mgif to find the version number, if it
even exists (it does in most of my codes)...


Changes
-------

Here are the major changes (1.x to 3.2):

    - Mgif is now more or less interactive only. It does not make
      sense to work batch with flicker mode. Most of the command
      line switches are gone.

    - There is now no file output (yet). I hope to develop some
      sort of file format for flicker palettes. Don't hold your
      breath, though. [ changed in 3.5, see below. ]

    - Image processing functions include histogram equalization,
      contrast stretching, inversion, blurring, brightening, median
      filtering, thresholding, log scaling, resizing (only powers
      of 2: 2x, .5x, ...), convolutions, etc.

    - GIF decoding is now a single entry point so source could be
      used for other applications. Flicker code is as well. Just
      pass it a pointer to the grayscale image along with its size.

Actually, I just submitted version 3.2 a few weeks ago. This post is version
3.5. The changes from 3.2 to 3.5 are:

    - Read Degas PI1/PI2 files as well (-pi1 and -pi2 switches).

    - Add cut option to cut out a piece of the image for further
      processing. Mgif can handle images with one or both dimensions
      larger than the screen, as long as the image itself is smaller
      than MAXIMG (now 400,000) pixels.

    - Add option to selectively enlarge/shrink by direction, vertical,
      horizontal, or both.

    - Fix bugs (actually out right algorithmic errors) in median, log
      scaling, and a couple of other things.

    - Add a file save option (*.fl files) and a viewer for these
      "flicker" files. These files are just a header and copies of
      each screen used by the flicker routines. Note that to save
      space, only the actual used part of the screen is saved. For
      example, a 320x200 image uses about 24k (1/4 of each of the 3
      screens). A .fl viewer is also added to mgif now using the
      switch -fl. Note that you either view GIFs/PI*s or FLs, not
      both at the same time. I have also included in the source post
      a standalone viewer, showfl. Both mgif and showfl will attempt to
      make a mosaic of several files which is useful for comparing
      the results of your image processing. Realize that there are
      only 640x400 pixels to work with, so it displays up to 4 320x200
      images, up to 6 200x200 images, or up to 2 320x400 images.

    - Change point coord specifications (e.g. in cutting) from numerical
      input to arrow key-driven crosshair. Much easier this way!

    - Add zoom option which uses an arrow key-driven box to detect
      a rectangle to enlarge. This is currently always a 2x zoom
      i.e. width and height of zoom area are half image size. The
      resulting image is the same size as the original.

    - Can copy raster images for transformed area to original area and
      visa versa. Doing so will destroy the image in the copied to area.
      This is like a checkpoint of a long processing train that may
      split where if it does not work out, you want to go back to an
      intermediate image.

    - A histogram is also displayed directly on the flicker screen.
      Some word about the flicker drawing is required. When the routine
      is entered, it draws one of the flicker planes to the screen and
      the other two to buffers. During this time, any key will stop
      this process and the partially rendered image is flickered instead.
      After the flicker is set up, the actual draw starts by slowly
      cycling through individual screens (just so you can see them).
      This, too, can be interupted with a single key (any). The fully
      speed flicker should appear after 2-3 seconds. It stays there until
      you press any key. After that, a histogram is mapped onto each
      flicker screen and the image displayed until a key is pressed.
      Finally, the histogram is replaced with the portion of the image
      it overlaid, and you go back to the command line.


More of what it is
------------------

Mgif uses Floyd-Steinberg dithering to represent color images on bi-level
devices as well as the so-called "flicker palette". I was graciously
presented with a copy of some routines to do the flicker stuff from
Klaus Pedersen ([e-mail]) and I adapted it for use with mgif. He
used a combination of F-S and rapid (Vsync) screen switches, resulting in
suprisingly good grayscale image quality on a monochrome monitor. This is
a major win, IMHO. Thanx, Klaus! I think mgif's original F-S dither was
better than Klaus's without flicker, but the flicker trick really blows
away ANY simple F-S. The F-S dither implemented always scans left to
right to propagate errors. A better way is to alternate directions on
alternate scan lines for even better image quality. I have not had time
to change this, however. The code is pretty dicey as it is, so I invoked
the usual principles of (good) software engineering: KISS, INBDFI (If Not
Broke Don't Fix It), etc.

It handles reasonable image sizes, but clips to max of 640x400. Reasonable
here means PC-ish (640x480 VGA, etc) images, not megapixel images which
need a heck of alot of memory and/or different coding methods (i.e. GIF
direct to screen). It should handle up to 8-bit images (which is max GIF
format, I believe). I have limited the size of the internal arrays to hold
the raw GIF image and the decoded image. It could fit on an empty 1 MB system
(if recompiled) and will handle images up to 400,000 pixels, plus or minus.
The included binary will need 1.4 MB of memory. To get it to fit on a
1 MB system, change the CodedGIF[] array dimensions to about 150,000 and
the Raster[] and TransRaster[] array dimensions to 310,000. It should then
be able to handle most images 640x480 or smaller in 1 MB. I have not tried
this (since I have a mega 4) so you may need to play around. Look at the
mgif.h file for the defines. The especially daring can patch the binary.

Mgif is pretty big and as compiled will not fit on a 1 MB system. The size
of the executable is:

    43292+12030+1330634+0 1385956

plus a stack of 32k, as I recall. The big space is 2 (static) buffers of
size MAXIMG (400000) and 1 of size MAXRAW (also 400000 bytes). This allows
images up to 640x620 or so to be read, thus easily accomodating PC-ish GIF
images of size 640x480 or smaller. You can always recompile for lesser
memory systems. Try (in mgif.h) MAXRAW of 190000 and MAXIMG of 300000. This
should make it squeeze into a 1 MB system, without DAs, TSRs, or whatever,
and should still handle images up to 640x480 pixels. MAXRAW is for the
coded GIF file (before LZW decoding). I read it into memory to try and
speed up the decode. This, too, can be changed, to do it on the fly. Since
I generally have 2 MB of free memory, I don't really worry about it. I also
don't even try really large images just because it takes too long. Note
that I don't thing ReadGIF checks to see if the coded file will fit into
the space provided, so there may be a problem if you reduce MAXRAW with
especially large images. The is no problem as distributed, other than
you need at least 1.4 MB of free memory.

There are 2 posts: binary and source. If you make any significant
enhancements, I'd appreciate a copy (source), especially if it speeds things
up. I made the tradeoff of speed for modularity. Stuff in ReadGIF could
be inlined and simplified. However, this is pretty much the way it came
from PBMplus, more or less. It takes 15 to 25 sec to decode a 320x200 image
which is not too bad. Also, the conversion to grayscale should go much
faster. Flicker goes about as fast as it is going to go without major
changes (like inlining, etc). Some of the area processes should be faster
as well, especially enlarging. All in all, it may take 50 to 60 seconds
to read, decode, and display a 320x200 GIF file.

Also note, that because of its modularity, you can easily add the ability
to read other file formats (like Spectrum). Just put the hooks on on the
command line (a la "-pi1") and add a ReadWhatever() routine to decode the
file. Someday I may add an option to read PBMplus PGM (graymap) or PBM
(bitmap) files.

The raster array contains an index for each pixel into a RGB color
table. You set up the raster and the color map. See ReadPI1 for an good
example (which also re-quantizes PI1 8 index palettes into 256 values via
a simple table lookup). No serious checking of command line file names is
done (is that REALLY a .gif file?) so be careful. It should kick you out,
however, if the file's "magic number" is bad, however.

It is also fairly easy to patch in new image processing algorithms. If
people do this, I'd appreciate source.

enjoy...

-bill rosenkranz
[e-mail]




Binary manifest:

Name          Length    Stowage    SF   Size now  Date       Time    CRC
============  ========  ========  ====  ========  =========  ======  ====
CURLEY.FL        24266  Squeezed   23%     18859  19 Jun 91   0:19a  2AE0
MGIF.1           18389  Crunched   50%      9228  15 Jun 91   4:43a  EF18
MGIF.TTP         69834  Crunched   45%     38757  19 Jun 91   0:02a  E371
README           12407  Crunched   43%      7127  19 Jun 91   0:42a  0014
TODO               693  Crunched   29%       496  19 Jun 91   0:34a  2AE6
        ====  ========            ====  ========
Total      5    125589             41%     74467

Note that MGIF.1 is the formatted manpage with imbedded control chars for
use with manpager. If you don't use manpager (shame on you!) you can either
edit this file, removing the vt100-ish escapes, or reformat the document
with nroff.

CURLEY.FL is a flicker file. View with:  mgif -fl curley.fl. It was made
from curley.gif (about 35kB, 320x200x256 image). You MUST use a monochrome
monitor! No checks are made if you don't. It probably WILL CRASH YOUR SYSTEM
if you try this with a color monitor! Consider yourself warned...


Source manifest:

Name          Length    Stowage    SF   Size now  Date       Time    CRC
============  ========  ========  ====  ========  =========  ======  ====
FILE.C            5341  Crunched   50%      2673  15 Jun 91   1:50a  5F32
FLICKER.C        22285  Crunched   52%     10784  14 Jun 91   2:28a  1518
LINEA.S           2740  Crunched   45%      1534  15 Jun 91   0:13a  D75D
LOW.C            21604  Crunched   54%     10109  14 Jun 91  11:43a  DB2F
MAKEFILE          2518  Crunched   44%      1424  19 Jun 91   0:50a  F53C
MGIF.C           52391  Crunched   53%     24673  18 Jun 91  11:43p  4500
MGIF.H            3240  Crunched   48%      1715  13 Jun 91   9:49a  37D7
MGIF.MAN         17497  Crunched   48%      9128  15 Jun 91   4:31a  0B46
PROCESS.C        38784  Crunched   60%     15857  15 Jun 91   0:02a  87BC
READGIF.C        26038  Crunched   55%     11855  13 Jun 91  10:42a  70F4
README           12407  Crunched   43%      7127  19 Jun 91   0:42a  0014
READPI.C         11591  Crunched   54%      5348  13 Jun 91  10:42a  BE3F
SHOWFL.C          8730  Crunched   51%      4329  19 Jun 91   0:22a  E53D
SHOWFL.MAN        1432  Crunched   32%       984  15 Jun 91   1:33a  80C8
TODO               693  Crunched   29%       496  19 Jun 91   0:34a  2AE6
        ====  ========            ====  ========
Total     15    227291             53%    108036