home *** CD-ROM | disk | FTP | other *** search
/ Crawly Crypt Collection 1 / crawlyvol1.bin / graphics / mgif42b / mgif.1 next >
Text File  |  1993-07-02  |  13KB  |  320 lines
  1. NAME
  2.    mgif - display colour images in grey scales and manipulate them
  3.  
  4. SYNOPSIS
  5.    mgif -fl [-m] file.fl ...
  6.    mgif [flag] ... wildcard ...
  7.       flags: -x, -xx, -n, -i, -v, -vers, -c, -w, -p, -p0 n, -p1 n, -h
  8.  
  9. DESCRIPTION
  10.    MGIF 4.2 displays colour images in four grey scales in any of the ST and
  11.    Falcon030 bitplane modes, and probably the TT modes as well, using a
  12.    flickering technique and Floyd-Steinberg dithering to get fantastic
  13.    results. In the Falcon true colour mode 32 grey scales are shown, with
  14.    dithering, which looks even better.
  15.    For best results at least 640x400 pixels at 60Hz is recommended.
  16.    A selection of image processing tools can be aplied to the image to
  17.    enhance it or produce interesting effects.
  18.  
  19.    Versions up to 3.7 of this program were written by Bill Rosenkranz, but
  20.    development is now continued by Johan Klockars.
  21.  
  22.    The currently supported image file formats are:
  23.  
  24.       GIF  - extension .GIF             (GIF87a and GIF89a)
  25.       JPEG -   - " -   .JPG or .JPE     (only the JFIF file format)
  26.       PI1  -   - " -   .PI1
  27.       PI2  -   - " -   .PI2
  28.       FL   -   - " -   .FL              (this is MGIF's own format)
  29.  
  30. OPTIONS
  31.    -x    Use extra JPEG colour decoding steps to get better results.
  32.          Without this option a faster grey scale decoding is used.
  33.          This option has no useful effect in this monochrome only version.
  34.  
  35.    -xx   The same as -x
  36.  
  37.    -n    Do not use dithering in JPEG decoding process.
  38.          This option has no useful effect in this monochrome only version.
  39.  
  40.    -i    Inquire about the files but do not display them.
  41.          Ouput contains information like image size, number of bits per
  42.          pixel etc.
  43.  
  44.    -v    Show verbose messages.
  45.  
  46.    -vers Show MGIF version information.
  47.  
  48.    -c    Do not copy image from the flicker screens to the normal screen at
  49.          return to command line mode. Very useful when you run mgif from a
  50.          window, such as MiNT/toswin or gemini/mupfel.
  51.  
  52.    -w    Wait for key at startup. Useful if you run mgif from floppy and want
  53.          to change disk before loading begins.
  54.  
  55.    -p    Use pipe for command input instead of the usual interaction.
  56.          This is not yet functional.
  57.  
  58.    -p0 n Allocate n Kb memory for the original picture.
  59.          The default is about one third of the available memory, but not
  60.          more than 1 Mb.
  61.  
  62.    -p1 n Allocate n Kb memory for the new picture.
  63.          The default is about one third of the available memory, but not
  64.          more than 2 Mb.
  65.  
  66.    -h    Show help text.
  67.  
  68.    -fl   Load files in MGIF's own flicker file format. If not the -m option
  69.          is used, the pictures are shown sequentially.
  70.          Press any key to go to the next file.
  71.  
  72.    -m    Create a mosaic of flicker files. Several images can be displayed
  73.          on one screen if they are all small enough.
  74.          Two 320x400, four 320x200 or six 200x200 images are displayed
  75.          together. Other sizes are treated as the nearest larger size.
  76.  
  77.  
  78.    wild  One or more standard wildcards with extensions as above. If a file
  79.    card  has no extension it will be treated as if it was a GIF image.
  80.  
  81. INTERACTIVE COMMANDS
  82.    The following commands are available at the prompt:
  83.  
  84.    Control Commands
  85.  
  86.       h     Help
  87.             Prints a brief summary of the available commands.
  88.  
  89.       q     Quit
  90.             Move to the next image given on the command line. If there
  91.             are no more the program exits.
  92.  
  93.       <ESC>
  94.             Exits the program.
  95.  
  96.       <SPACE>
  97.             Draws the current image.
  98.  
  99.       <ENTER>
  100.             Shows last drawn image again.
  101.  
  102.       w     What
  103.             Displays information about image, buffers, load time etc.
  104.  
  105.       hi    Histogram
  106.             Plots the intensity histogram of the current image.
  107.  
  108.       o     Toggle Original
  109.             Toggle the current image, original/new.
  110.             Transformations are cumulative only if "new" is current.
  111.  
  112.       f     File Operations
  113.             The only available file operation is to save the last screen
  114.             image to a special file having the .FL suffix. This file
  115.             will contain the three screen images which are used by the
  116.             flicker routine to simulate grey scale.
  117.             In order to save an image in this format you must first
  118.             display it completely by the flicker routine, ie do not
  119.             escape the actual screen draw but let it finish.
  120.  
  121.       cp    Copy
  122.             Copy the new, transformed image, to the original or the
  123.             other way around. The former is the most useful.
  124.  
  125.       Display Options
  126.  
  127.       n     Noise
  128.             Adds noise. Not to the image itself but to the dithering
  129.             process. This can help in images which have artificial
  130.             banding as a result of the dithering process. You are asked
  131.             for a value which is a percentage (0 to 100).
  132.             Each time "o" is toggled, noise is reset zo zero (off).
  133.  
  134.       g     Laplace filter
  135.             This, like noise, is not applied to the image itself but
  136.             rahter in the dithering process. It helps to define hard
  137.             edges in images and implements a Laplace filter. A
  138.             quantity, Beta, is required. A value of one corresponds to
  139.             a Beta of 0.25, a value of two corresponds to a Beta of 0.50
  140.             etc. A value of zero turns off Laplace filtering.
  141.             It is possible to get the same effect by giving a suitable
  142.             matrix to the convolution function.
  143.             Beta is reset to zero when "o" is toggled.
  144.  
  145.       Frame Processes
  146.  
  147.       e     Enlarge
  148.             Enlarges images two times. You can choose which dimensions
  149.             should be enlarged as either horizontal, vertical or both.
  150.             The new pixels inserted are given the average intensity of
  151.             their neighbours.
  152.  
  153.       s     Shrink
  154.             Reduces images two times. You can choose which dimensions
  155.             should be reduces as either horizontal, vertical or both.
  156.             Every other point is thrown away when reducing.
  157.  
  158.       z     Zoom
  159.             Use the arrow keys to move around a window covering one
  160.             fourth of the picture to choose which part to enlarge two
  161.             times. The shift keys can be used to position the window
  162.             with pixel accuracy. When you are satisfied, press the
  163.             <INSERT> key. At any time any other key aborts zooming.
  164.  
  165.       cu    Cut
  166.             Cuts out a rectangular area of the image.
  167.             A crosshair can be moved around as described under "zoom"
  168.             above to select first the top left corner and then the
  169.             bottom right corner. Selection is by the <INSERT> key.
  170.             The crosshair can be moved outside the screen area if the
  171.             complete image is too large to fit on screen. The coordinates
  172.             shown on screen will still show the correct values, but the
  173.             crosshair itself will of course not be visible. 
  174.  
  175.       r     Rotate
  176.             Rotate the original (not the new) image any integer angle, from
  177.             -180 to 180 degrees, counter clockwise. Any changes done to the
  178.             new image are lost, so you'll be asked to confirm the operation
  179.             if the new image is the current one.
  180.  
  181.       mi    Mirror
  182.             You can mirror the image horizontally or vertically.
  183.  
  184.       x     Shear (not shown on help screens)
  185.             Shear image horizontally or vertically a specified amount.
  186.             This is not really documented yet.
  187.  
  188.       y     Scale (not shown on help screens)
  189.             Scale image horizontally or vertically to a specified size.
  190.             This is not really documented yet.
  191.  
  192.       Point Processes
  193.  
  194.       hi    Histogram equalization
  195.             This operation attempts to smooth out images with skewed
  196.             or narrow histograms. The intensity values are redistributed
  197.             to match their occurence frequency.
  198.  
  199.       i     Inversion
  200.             This is a bit more general than a simple digital negative.
  201.             A threshold value is needed and this is used as follows:
  202.  
  203.             threshold == 0:
  204.                new[i] = 255 - old[i]         Invert pixel
  205.  
  206.             threshold < 0:
  207.                if old[i] < -threshold        Old intesity < -threshold?
  208.                   new[i] = 255 - old[i]         yes, invert pixel
  209.                else
  210.                   new[i] = old[i]               no,  don't change
  211.  
  212.             threshold > 0:
  213.                if old[i] > threshold         Old intensity > threshold?
  214.                   new[i] = 255 - old[i]         yes, invert pixel
  215.                else
  216.                   new[i] = old[i]               no,  don't change
  217.  
  218.       l     Logarithmic scaling
  219.             Scale each pixel's value to the ratio of the logarithm of
  220.             the pixel's intensity and the maximum intesity in the image.
  221.  
  222.       t     Threshold
  223.             Makes all pixels above a given threshold intensity white
  224.             and all below the threshold black.
  225.  
  226.       co    Contrast expansion
  227.             Attempts to expand the contrast of an image to cover the
  228.             entire range of 256 allowable grey scales. A threshold
  229.             value is used to remove intesity levels at the top and
  230.             bottom of the histogram. The histogram is searched from the
  231.             top and bottom for the first intensity level with more
  232.             pixels than the threshold. The pixel intensities are then
  233.             changed as follows:
  234.  
  235.             new[i] = 255 * (old[i] - low) / (high - low)
  236.  
  237.             where [low,high] is the new contrast range
  238.  
  239.       br    Brighten
  240.             A constant intensity is added to every pixel.
  241.             A positive number brightens the image and a negative
  242.             darkens it. Any new values outside the range 0-255 are
  243.             limited to these values.
  244.  
  245.       Area Processes
  246.  
  247.       bl    Blur
  248.             Each pixels intensity value is changed to the mean of
  249.             the nine pixels in the surrounding 3x3 square.
  250.  
  251.       me    Median
  252.             Each pixels intensity value is changed to the median of
  253.             the nine pixels in the surrounding 3x3 square.
  254.  
  255.       v     Convolution filters
  256.             Apply one of a number of 3x3 convolutions to an image.
  257.             Choose one of the built-in filters or enter 0 for user
  258.             defined. In the latter case, enter the nine numbers of
  259.             the convolution kernel along with a flag if there will
  260.             be a multiplier (or divisor). Then enter that scaling
  261.             factor if needed. All quantities are integers.
  262.             Each pixels intensity value is changed to a value
  263.             calculated by multiplying the pixel intensities of the
  264.             pixels in the surrounding 3x3 square by the corresponding
  265.             factor in the kernel matrix and summing these up. If a
  266.             multiplier or divisor is used this is also applied to the
  267.             new intensity.
  268.  
  269. FILES
  270.    *.GIF    GIF image files.
  271.    *.JPG    JPEG (JFIF) image files.
  272.    *.JPE          -   "   -
  273.    *.PI1    Degas low resolution files.
  274.    *.PI2    Degas medium resolution files.
  275.    *.FL     MGIF flicker files.
  276.  
  277. SEE ALSO
  278.    gif(5)
  279.    Gonzales and Wintz, Digital Image Processing.
  280.    Lindley, Practical Image Processing In C.
  281.    Burger and Gillies, Interactive Computer Graphics.
  282.    Anil K Jain, Fundamentals of Digital Image Processing.
  283.    Foley/Van Dam, Computer Graphics: principles and practice.
  284.  
  285. DIAGNOSTICS
  286.    Various warnings when corrupt files are given as input, when memory is
  287.    insufficient etc. If an error occurs during a processing function, the
  288.    prompt line will indicate the error. 
  289.  
  290. NOTES
  291.    This program is still under development and all comments or suggestions
  292.    for improvements are welcome.
  293.    The complete sources for this program are available. Contact me if
  294.    you're interested and can't find them.
  295.    Sources tested on: GNU C 2.4.4, Lattice C 5.52, Turbo C 1.0 
  296.  
  297. BUGS
  298.    Please, report any bugs you find to me (Johan) at the address below.
  299.  
  300.    Logarithmic scaling needs real logarithms.
  301.    The flicker file format is not fully defined.
  302.  
  303. TODO
  304.    (in priority order)
  305.    Batch operation using MiNT pipes.
  306.    Better support for extra grey scales on colour monitor.
  307.    Use of the DSP in the Falcon030 for image processing and unpacking.
  308.    GUI using GEM.
  309.  
  310.    And of course any good suggestions I get from you.
  311.  
  312. AUTHORS
  313.    Johan Klockars  (d8klojo@dtek.chalmers.se)  Current developer.
  314.    Bill Rosenkranz (rosenkra@convex.com)       Original author!
  315.    Frank Möhle                                 Added JPEG support.
  316.    Klaus Pedersen  (micro@imada.dk)            Wrote original flicker code.
  317.    Howard Chu                                  Added overscan support etc.
  318.  
  319. VERSION
  320.    mgif 4.2   93-07-01